DITA For Small Technical Documentation Teams

Overview of Tools Proposed for the Solution

The following list of tools and application will be used in our solution:

Content Management and Workflow: Github for storing the DITA content.; Github for creating and managing issues.
Editing: Oxygen XML Author for editing the DITA content and for offline publishing.; [Optional] Oxygen Web Author for online editing/reviewing of DITA content.
Review: [Optional] Oxygen Content Fusion for creating review tasks for subject matter experts.
Publishing: Oxygen XML Author for publishing from inside the application.; [Optional] Oxygen Publishing Engine for publishing to PDF and WebHelp DITA content on an integration server.; [Optional] Oxygen WebHelp Feedback engine for embedding feedback forms in the HTML pages.; [Optional] Gradle to script the publishing in preparation for an integration server.; [Optional] Netlify to build and host a web site for the DITA content.; [Optional] Oxygen Validate and Check for Completeness used with a scripting license to check for validation problems on an integration server.

The same set of tools has been used for editing and publishing the Oxygen XML Blog: Welcome!.

Learning DITA

There are various online resources for learning DITA, there are also learning DITA courses held by consulting companies. This older blog post has some useful links: Resources for learning DITA with Oxygen.

Project Storage - Using GitHub

You need a system to:

Store your DITA content.
Collaborate with your colleagues on writing content in the same project.
Allow for reviewers to propose changes without having the right to commit changes.
Have a history of changes on each DITA resource, being able to revert to previous versions of topics.
See who changed what content in each DITA topic and map.
Be able to tag releases so you can build manuals for older releases with some changes applied to them.
Maintain a list of issues which are closed as your work progresses.

Some small teams instead of using a version control system resort to shared network drives. Shared network drives do not address all the features above and they are dangerous in the fact that you can overwrite other people's work and there is no way to revert changes.

A free Github account can cover all these use cases listed above. GitHub exposes through a web interface access to a Git repository. This blog post is not about learning Git, it's about having minimum Git skills to get you started. There is a good book about learning Git Here: https://www.manning.com/books/learn-git-in-a-month-of-lunches.

We'll outline below some steps to get you started with a GitHub project:

Create a GitHub account: https://github.com/join.
Create a new public or private repository in the organization for your project.
Create an organization: https://github.com/settings/organizations. The organization will be useful to group work-related projects. For adding private repositories in an organization you will need to switch to a paid plan.
Add your team members to the organization. Using the team member GitHub user names you can send them invitations to be contributors to the project.

Creating and Modifying Content in the Repository

You can create and edit DITA topics in a number of ways:

Edit topics offline and use GitHub's user interface to upload them, or modify existing topics using GitHub's web interface.
Use the Oxygen Web Author to connect to the Git Repository and create a new topic or modify an existing one.
Clone the repository to the local file system using Oxygen XML Author with the Git Add-on installed.

Using Oxygen XML Author to Create/Modify Content in the Repository

Install the Git Add-on in Oxygen XML Author.
Open the Git Staging view and use the + toolbar button to paste the reference to the reference to your project, for example https://github.com/oxygenxml/blog.
Choose a location on the local drive where the project will be cloned.
The Git Staging view does not show all existing resources in the project, it will just show the modified resources, so go to the Project menu and create a new Oxygen project in the folder where the project was cloned.
In the Git Staging view the newly created project.xpr should now appear. Select it, use the Stage Selected button to stage it, then write a commit message and use the Commit message to commit it. Now the file is committed in your local repository. You can use the toolbar Push button to push it to the GitHub account.
Create a DITA Map and a couple of topics using Oxygen's Project view.
Using the same Git Staging view you can see the newly added files, stage, commit and push them to the remote GitHub repository. You can check on the remote GitHub repository that the files were updated.
If changes are made by someone else using the same technique or if changes to maps and topics are made directly from the GitHub web interface or from the Oxygen WebAuthor, the Git Staging view has a Pull toolbar button allowing you to obtain those changes locally.
On resources which have been modified a number of times you can right click in the staging area and choose Show in history to see a history of changes. You can also choose Show blame to see who modified each of the lines in the document.

Here's a simplified overview of how you could work with Oxygen and Git:

Every time you start Oxygen or every time before you commit use the Pull toolbar button from the Git Staging view to get changes locally.
Stage and commit your changes, then push them to the remote repository.
If you attempt to pull changes including a file which is already modified locally by you, the pull operation will not succeed. You will need to copy that file separately, pull the content from the server and then compare your changes to the ones coming from the server and merge your changes.
If you have already committed to your local repository a resource modified also on the remote repository, you have a conflict, the Git Staging view allows you to edit the conflict, merge the changes locally and then commit to the local repository and push changes to the server.
You do not have to pull and push changes from and to the remote repository very often, you can continue working with your local repository for days and push all changes at the end but not pulling changes from the server often might result in various conflicts if the same resources are modified both on the server and in your local repository.

Organizing Your Project Structure using the Master Files Support

You can now start to organize your content. The Oxygen user's manual contains a Getting Started guide for DITA editing.

You can right click the Project root and enable main files, then in the Main Files folder add a reference to the main DITA map (or maps). All refactoring operations (move resources to subfolders, rename topics or resources) will properly update references in the entire DITA project hierarchy. A minimal DITA project would probably contain:

One or more main DITA Maps.
One or more DITA submaps, defining keys for reusable content.
One or more folders containing reusable DITA elements.
A folder containing one or more DITAVAL filter files.
A folder containing images or binary resources.

Overall management of the DITA project

The Search References contextual menu actions from the DITA Maps Manager and from the main editor allow you to check where a topic, map or image is being used.
The Remove from disk action in the DITA Maps Manager view will warn if the removed topic is used in multiple places.
Validation errors are issued for references to missing topics or images.
Move/Rename actions located both in the Oxygen Project and DITA Maps Manager view allow you to move topics/maps or images and have references to them automatically updated.
Search for references to IDs or rename IDs in the entire project.
The Find unreferenced resources contextual menu action in the DITA Maps Manager allows you to find orphan topics or other resources (images, etc).
You can define profiling condition sets and use them to see in the editing area what content is filtered, then use the same profiling condition sets for publishing.
The Open/Find Resource side view allows you to locate files by content.
The change tracking support in Oxygen allows you to make changes with change tracking or to add or reply to existing comments.

You can find out more DITA editing tips in the DITA Editing Tips And Tricks blog.

Sharing Common Settings using the Project

The Oxygen project configuration can save various sets of global options at project level. As an example:

Go to the Oxygen Preferences->Editor / Spell Check page and change the radio button at the bottom to Project Options. Then check the Automatic spell check checkbox.
The Git Staging view should have a modified version of the XPR showing as modified, stage, commit and push it.
Now everybody using the same project.xpr project file loaded in Oxygen will have spell check enabled.

Other useful settings you could switch to Project Options:

The Project Level Settings preferences dialog allows you to control if various settings are saved at project or global level. For example you can save the Validate and check for completeness settings at project level and share them with others.
The Editor / Spell Check / Dictionaries preferences page can contain your own set of dictionary terms.
The Document Templates preferences page allows you to use your own custom new file templates.
In the Editor / Save preferences you can save at project level various save options.
Switching the Menu Shortcut Keys preferences page to project level allows you to share with others custom menu shortcut keys.

You can use the ${pd} editor variable to refer to resources located in the current project folder. You can read more about editor variables here.

Manual Publishing

You can open DITA Maps in the application DITA Maps Manager view and publish them to various outputs using the Configure Transformation Scenarios toolbar button. A transformation scenario can also specify a DITAVAL filter, parameters and can be saved at project level. The published content can be later uploaded to a web server.

For WebHelp output you can create a publishing template containing custom CSSs, headers, footers and logos. The publishing template can be saved in the project and referenced from the transformation scenario.

For the PDF output the same publishing template can be used. To build your custom CSS you can use the Oxygen Styles Basket online CSS-builder.

If you are publishing multiple DITA Maps or you have multiple filters or multiple deliverable formats you may want to create a DITA Open Toolkit project file: https://www.oxygenxml.com/doc/ug-editor/topics/dita_open_toolkit_project.html. A sample DITA OT project file can be found in the Oxygen XML Blog project on GitHub.

Working with Branches

You may need to mark releases of your product and also to be able to contribute small fixes to those releases. So here's how you work with branches:

The default branch in the project is called master and this is the branch we've been working until now.
Using GitHub's web interface you can create your own branch.
Check out again in the Git Staging view the project, this time with the separate branch in a separate folder.
Open the project.xpr from that branch's checkout, make changes to the content there, stage, commit and push as usual.

Establishing a Workflow

You can use the GitHub issues list for your project to create new issues. You can attach files to the issue, assign the issue, discuss with other participants, register to watch particular issues. Once a commit is made with a particular #issue_number, the issue will get an automatic link pointing to the commit.

Inside an organization or inside a repository you can create project boards. A project board can define states for your issues. When an issue is opened it can be assigned to a certain project board. It can also be assigned various labels. Issues can also be assigned to various people in your team.

Oxygen's change tracking support allows you to insert or delete content with change tracking or to make comments on content. The Web Author online editing tool allows you to also make changes with change tracking.

The Oxygen Content Fusion add-on allows you to create review tasks and to allow subject matter experts to give you feedback on DITA content directly from a web browser.

Adding Custom Validation Checks to the Project

There are a couple of ways in which you can add custom validation checks to your project:

You can create a custom Schematron schema containing custom validation rules: Sharing Schematron Validation Rules.
The Validate and Check For Completion action from the DITA Maps Manager view contains various settings which can be saved at project level. In the Preferences->Project Level Settings page there is a Save DITA Map validate and check for completeness settings at project level checkbox.
You can also add terminology checking in the application: Checking Terminology with Oxygen XML Editor.
In GitHub projects you can configure custom actions and run validate and check for completeness with a special scripting license on pull requests. An example for such a validation action is in the Oxygen XML Blog: https://github.com/oxygenxml/blog/blob/master/.github/workflows/workflow.yml. The validation runs on any opened pull request: https://github.com/oxygenxml/blog/pull/25.

Adding Custom Actions

You can use a framework customization saved at project level to add custom actions which can be used in the Author visual editing mode and can be mounted in the toolbar, menus and the content completion window: Implementing a Custom Author Action to Split a Table.

Dynamic Publishing using an Integration Server

Using a bit of scripting you can publish the modified content on the fly with either using free online services like Netlify or Travis or using an internal Jenkins server. The Oxygen XML Blog is an example for this. It has a Gradle script which is run as part of a Netlify account whenever changes are made to the topics.

Translating your content

The Oxygen Translation Package Builder add-on allows you to find the changed resources in a DITA project and then to pack those changed resources and send them for translation. It also helps with integrating the received translation in the project. This blog post has more details and useful links about translating DITA projects.