A talk I recently heard reminded me of a little project I did that employed Eclipse, UML2 Use case modeling and Xpand to manage a complex DocBook manual for a software system.

We had a thick docbook manual for a software system. The structure of the manual was designed after the several input masks and menus. However, several user groups that used the tool could not find their workflows in the document and had to jump from section to section.  What we needed were role-specific documents that served as a guideline to support the different workflows. Several sections were required in more than one of the new manuals and we did not want redundancy. In addition, the original document had to be preserved as well for reference.

The contents were expected to change over time, since the software system was still evolving.  So we used several open source tools:

• Eclipse UML2 for modelling the roles (Actors) and the Use Cases
• The comment section of a use case was used to hold a reference to the fragment in the original document that held the relevant documentation.

Comments holt pointers to original documentation by means of Xpointer

• The new documents were created with oaw / Xpand: For each actor and top level use case, a dedicated docbook xml was generated. The structure of the document was simply the use case structure. Each document contained the xpointers that were definined in the use case descriptions.
• The following (existing) toolchain employed xslt transformations and created the .pdfs. It is mandatory, that the xml tools support the xpointer spec. There are only a few tools that actually do.

As a result, we generated user specific documentation in a quick way without having to rewrite a lot of text.