>Standards, Documentation, Single Sourcing, and Continuous Integration

>Over the last several years I’ve had the pleasure of working with many standard organizations. Many are trying to improve their development processes to meet the membership and the communities needs sooner. However, almost all have one area that still needs attention. Documentation.

In particular the way the documentation is generated. Documentation comes in may different forms:

  • Specifications
  • Naming and Design Rules
  • Implementation Guidelines
  • Whitepapers
  • Use Cases
  • Requirements Documents

The problem is that like most traditional software development, the documentation aspect is focused on the wrong pieces. Too much time is spent on pieces of the documentation that are quickly out dated. Not enough time is spent on the pieces that need to stay current. Most of these problems have to do with time and resource constraints, but also have to do with the way the documentation is integrated into the development process. Instead of making items like Implementation Guidelines and Specification updates an integral part of the process, they are put off to the very last step of the process

Information is also kept in multiple places and with tools that can not easily be automated or put into a build process. There is much that a standards organization can learn from the publishing industry. The practice of single sourcing is one of those items.

Single Sourcing allows you to maintain the documentation in one central format and then generate the needed pieces and parts for the items you want to produce. If you need Guidelines in PDF, HTML, Word, ODT, EPub, etc, maintain the guidelines in one format, that everybody can easily get to and update. The other piece of this is that the format should be able to be exported and automated. No manual intervention on generation of the content should occur.

One of the formats I’ve become fond of is DocBook. There are others like DITA that provide much of DocBooks benefits, but I’ve found that DocBook seems to hit the sweet spot when it comes to book documentation. DocBook along with the DocBook XSL project, allow the easy transformation of the documents into a variety of formats. If you are doing XML Schemas for your standards, you can setup a set of XSL stylesheets to help translate the documentation you have in the schemas to a DocBook file. Once in docbook, you can generate to a variety of output formats. The key here is that there is no manual intervention in the generation. As soon as your schemas are updated, and if you have a Continuous Integration build server running, your Guidelines and Specifications can be updated as well. This way information is not out of date, and you do not get descrepancies between various flavors of the documentation.

Standards organizations need to review the way they generate the documentation, so that they are meeting their communities needs sooner and more accurately.

This entry was posted in agile, docbook, documentation, standards. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s