Using DITA to Document a Software Product
Besides working on an XML editing tool 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:
- Online Help which is available as WebHelp Responsive on our website. Our WebHelp Feedback integration allows users to add comments and ratings to each topic. Those comments can later be used by us to rephrase and improve our documentation.
- PDF containing the entire contents of the user's manual. The PDF output is styled using CSS and obtained from DITA content using our Oxygen Publishing Engine. Nowadays, most of 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 among users.
- 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.
We have two main distributions (Standalone and Eclipse plugin) and three main products (Editor, Developer and Author). We also have a web editing tool, WebHelp generation plugin and publishing engines. So we need to produce more than 9 different publications from the same DITA content depending on the shipped product.
And here's an overview of the tools we use:
Git as a Version Control System
We store our DITA content in 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 free Oxygen Git client add-on for collaborating on the project. Other external Git clients like SourceTree or Fork can also be used to check out, edit and push changes to the Git repository. Our editing workflow is similar to what is described in this past webinar.
Oxygen XML Author
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 by the technical writers to write DITA content but we also have colleagues who review content and propose changes directly from the web browser.
Oxygen Content Fusion
The Content Fusion add-on for XML Author allows uploading the edited content to a cloud server and providing a web editing tool for people to provide feedback and review the DITA content directly in a web browser: https://www.oxygenxml.com/content_fusion.html.
Oxygen Publishing Engine
We use the Oxygen Publishing Engine (based on the DITA Open Toolkit) to publish DITA content to the outputs we are interested in, mostly WebHelp Responsive, PDF and Windows Help.
Jenkins integration server
We have an automated script which builds all the user manual outputs every night.
Automated DITA Content Validation
There is a Validate and Check for Completeness script which runs on a test server and does various types of checks on the DITA content (including checks for validation, filtering problems, broken links, etc).
Atlassian Jira for Ticketing and 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.