A while ago, I wrote an entry called Agile Documentation, in which the development of documentation or any particular writing and publishing process can be made agile. This was driven home recently with some changes at work. We publish a variety of specifications and guidelines for the standards we develop, and in some change is quite frequent. The issue when maintaining any type of documentation has always been keeping it up to date.
As stated in Documentation is a Deliverable, developers fundamentally do not like writing end user documentation. The problem is that when you are a small company, or working in a small open source project, developers may have to write documentation. This isn't much of a problem when the project starts out as it's fairly easy to write the code and then go back later and update the documentation. However as the project grows, it becomes more difficult. Eventually the documentation is sorely out of date. WikiText can help in some aspects, as it lets the community maintain and contribute to the documentation easily. However, how are intellectual property rights, and copyright handled? Does the documentation that the community write need to go through IP review and copyright review? Maintaining documentation on a Wiki and generating the official documentation from there is good, but not perfect. No solution really is.
I have just moved several documents averaging over 100 pages each to DocBook format. This new process follows an agile approach. This means:
- All Sources Checked in regularly and synchronized with the source code repository.
- Automated builds for all destination formats.
- Continuous Integration builds of all relevant documents. As soon as source files are checked in, all documents are regenerated.
- Build notification failures. Verified by looking for particular strings and error code reports.
- Milestone Builds available for review every two weeks.
- Nightly Integration builds for those that must have the latest copy in a human consumable format.
- Publication/Release builds that remove the Draft Watermarks.
The advantage is immense. By moving away from Word and Open Office for the documentation, it has freed me to worry about the content, not necessarily how it is formated. The formatting is setup using the DocBook XSL Stylesheets and once the initial configuration is done, it's done. No tweaking, no adding extra blank lines. I can just concentrate on the content.
Writting documentation does not have to be a chore, or a painful process. Treat it like any other agile project, working as requirements are discovered, keeping to one common source format, and generating the rest automatically. Do it sooner rather than later, and the documentation you produce is much more relevant for your user community. If you are understaffed then take advantage of technologies that let the community help create and maintain the documentation. Just be careful of any copyright or IP issues that may arrise and have to be reviewed. Keeping documentation is relevant and a key to keeping your user community active and vibrant. Poor documentation is one of the pitfalls you want to avoid and can avoid.
Posts
Great to see another article promoting documentation as part of a project's deliverables.
Your article implies that the use of WikiText means that documentation must be maintained in a wiki. While it's possible to use WikiText with a wiki to maintain documentation, it's also possible to use WikiText with documentation stored in a version control system such as CVS or SVN. Two great examples of this are Mylyn (where the documentation is maintained online) and Mylyn WikiText (where the documentation is stored in CVS). Either way the same build-time transformation process can be used as described in your article.