Collaboration for Documenting a Software Product using DITA
Besides working on an XML Editor with lots of DITA editing functionality we also use DITA internally for editing the Oxygen User's Guide.
In this article I will try to give you an overview of our entire workflow as evidence that DITA does work and that it can be used and implemented without expensive solutions.
First here's an overview of our needs:- Offline Help which is available inside the installed application. Oxygen is a multi-platform application so we need to generate both HTML Help (CHM) for Windows and JavaHelp for the Mac OSX and Linux installations. Also for the Oxygen Eclipse Plugin we need to generate Eclipse Help.
- Online Help which is available as WebHelp with Feedback on our web site and allows users to add comments to each topic. Those comments can then be used by us to rephrase and improve our documentation.
- PDF containing the entire contents of the user's manual. Nowadays most our users use the online WebHelp because it can be used much easier for finding certain topics so in our case at least the PDF output is not popular anymore along users.
We have two main distributions (Standalone and Eclipse plugin) and three main products (Editor, Developer and Author). So we need to produce about six (6) different publications from the same DITA content depending on the shipped product.
And here's an overview of the tools we use:
Oxygen XML Editor
This may not come as a surprise but we use our own product to edit DITA content, partly because it's ours and partly because it is a very good tool. During the last couple of years this has been a good opportunity to improve our product based on our own feedback (feedback coming from our technical writers).
Oxygen is used in two ways:- By the technical writers to write DITA content.
- By the reviewers to review documented issues by adding comments, making changes with change tracking enabled.
DITA Open Toolkit + WebHelp plugin
We use the DITA Open Toolkit to publish DITA content to the outputs we are interested in. The WebHelp and WebHelp with Feedback outputs are our own additions to the DITA Open Toolkit. But we do not use any special customizations for the other outputs.
Jenkins integration server
We have an automated script which builds all the user manual outputs every night.
- Validate and check for completeness, check for broken links, images, broken web links and so on.
- Check and report topics, resources and images which are no longer referenced anywhere.
- Spell check the entire DITA content.
Git as a version control system
For a long time we used Subversion for version control. Recently we moved our DITA content to a private GitHub repository and we also made a public GitHub repository containing a copy of our user manual's DITA content:https://github.com/oxygenxml/userguide. We use the SourceTree application to work with Git and we are quite happy with it.
Atlassian Jira for workflow
We use Atlassian Jira to provide a workflow both for the issues which are related directly to our software product and for the issues which are related exclusively with our user's manual. The JIRA is integrated with both our SVN and GIT repositories so it shows for a certain issue all resources which have been modified to fix it.
More details about how with work with DITA can be found in these slides I presented at DITA Europe 2014:https://www.oxygenxml.com/forum/files/usingDitaForOxygenUsersManual.odp.
Video demonstration showing how collaboration on a technical publication with Subversion can be achieved: https://www.oxygenxml.com/demo/Collaborative_Authoring_Using_Subversion.html.