Wednesday, November 26, 2014

Collaboration for Documenting a Software Product using DITA

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

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:
  1. By the technical writers to write DITA content.
  2. 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.

Automated DITA Content Validation

There is a script which runs on a test server and does three types of checks on the DITA content:
  1. Validate and check for completeness, check for broken links, images, broken web links and so on.
  2. Check and report topics, resources and images which are no longer referenced anywhere.
  3. 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: 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:

Video demonstration showing how collaboration on a technical publication with Subversion can be achieved:

Saturday, November 15, 2014

Alternate sales pitch

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

This year was my first participation at Tekom Europe, we had lots of discussions with interested potential customers and one of them asked me to give him my sales pitch of why he should buy my product instead of a competitor's one. I'm not a salesman. I've always wanted to work for a product which is so good that it sells itself. And I do.

So here's my alternate sales pitch:

Ideally whenever you choose between any two software products which will be used daily by people in your company you should make a pilot test project with two user groups made of the people who will be actually using the product after it is bought. Ask them to use the product for a month performing tasks similar to what they will do after the purchase. Ask the two user groups at some point to switch products and see how that goes. And in the end let most of the decision to be made by these people who will actually be using the product in their work.

Working for an extended period of time with the product will also show how stable the product is, if it crashes often, if it has small annoying bugs and if it sometimes behaves unpredictable.

We are a productivity application and in my opinion the goals of such a type of application would be these ones:
  • shorten the amount of time users spend doing their daily tasks
  • allow users to fulfill their tasks with the least amount of frustration, let them concentrate on what should be done and not on the tool which is used in that process, be intuitive and easy to use

Look what types of operating systems are used in your company, can the tool run on all of them?

Read the product's End User License Agreement, I know it's a boring task but you might find some gems in there. For example does the user based license allow the user to install the product on multiple computers as long as he/she is the only one using it?

During the trial period ask questions on the technical support email address.
  • Are they responsive?
  • Are they helpful?
  • Do they know what they are talking about?
  • Do they go that extra mile to help you?
  • Is there a public forum available? Is it well kept, does it have a lot of activity?
  • Is there an user's list available? Register on it, see how questions are answered.

Find out how long the company which makes the product has been in business. Google the product online, read blogs and look for opinions on it.

In the end it will come down to two things: quality and price. But you need to make sure you are listening to the people who will actually use the application.

Tuesday, November 04, 2014

Public hosted Oxygen Plugin and Framework Projects

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
All resources, Frameworks and Plugins which we make publicly available to contributors can be found on the oxygenxml GitHub group:

Besides there are interesting Oxygen plugins and frameworks which are developed as separate public projects and maintained by third parties (either users or companies). I will try to compile a list below:

  1. Project Argon by German company Axxepta provides a plugin which can connect Oxygen to a BaseX server: The integration also provides CMS-like capabilities for searching and version control.
  2. You can define terminology terms and then create Schematron rules for them using the Doctales terminology checker Oxygen framework:
  3. Three open-source frameworks for editing ATA-2300, S1000D and RIF XML documents in Oxygen developed by Amplexor:
  4. Besides being bundled with Oxygen the TEI framework is also available as a project partly maintained by the TEI community:

    HisTEI: An Oxygen framework for historical documents encoded in TEI.

    More details:,

  5. Ediarium is an extension package for TEI editing within Oxygen.

    More details:,

  6. TEI Facsimile Plugin offers a side view in which users can load an image and see the marked areas (all the zone elements from a TEI document), draw new areas over the image and copy them into the editor:
  7. Framework which adds JATS/NLM support for Oxygen developed by Wendell Piez:
  8. Fork of the JATS framework which adds Schematron checks and Literatum package building:
  9. Automatic builder for Oxygen frameworks which allows user to describe framework's behaviour by using only XQuery, HTML, and CSS, and automatically generate the framework archive ready to be deployed (developed by Claudius Teodorescu):
  10. Plugin developed by Clausius Teodorescu which allows opening a JavaFX-based web browser in Oxygen:
  11. LanguageTool plugin for Oxygen:
  12. Framework for validating XSL-FO with Antenna House extensions developed by Antenna House:
  13. Framework which adds Daisy support in Oxygen:
  14. Framework which adds STRATML support to Oxygen:
  15. S1000D Framework which adds some limited support to edit S1000D documents in the Author visual editing mode:
  16. OpenDocs Plugin allows you to focus on specific file types opened in the editor in order to perform various actions on them: GitHub repository:
  17. XsltGui Project by Patrik Stellmann is an example of how you can show dialogs to the end users from an XSLT script:
  18. Workspace containing sample Oxygen plugins implemented in Javascript:
  19. Plugin developed by pagina GMBH which expands a custom editor variable called ${clipboard} to the clipboard contents:
  20. The NameDropper Oxygen plugin can be used to simplify the process of tagging names in XML and associating those names with authoritative identifiers:
  21. Sample Oxygen plugin demo by Tobias Fisher:
  22. A Workspace Access Plugin for Oxygen XML Editor that creates TEI-conform UUIDs starting with a letter:
  23. TEI Authorizer is a plugin for Oxygen which lets you query remote authority files via HTTP and use retrieved data to autocomplete attribute values in your TEI documents and define and implement forms to fill out new data and post it to your server via HTTP:
  24. Framework for editing UBL documents (UBL 2.1, 2.2 csd01 and 2.2 Pre-award csd02wd01pa01) developed by G. Ken Holman:
  25. Framework for validating OASIS genericode 1.0 documents developed by G. Ken Holman:

If anyone else wants to add something else to the list, just drop us an email.