Documentation
This is the point were we have to credit the existing documentation procedures which were in operation prior to our arrival or the start of this programme of development. This section exists to remind everyone how vital documentation is to the long term success of your projects and to provide some examples of how the process worked.
Make your own Documentation
HEAnet operate a system of documentation were each admin was responsible for producing documentation for their area of expertise and forwarding it to the editor who then placed the work in the overall documentation. Our system was based on SGML which provided many benefits including automatic generation of online and printed documents. While there is an initial learning curve for the editor it is well worth the effort.
However all was not well, there was no change control on the documentation tree and it could only be processed on one workstation on the network, the tools being uninstallable on other hosts due to dependancy problems. Plus writing documentation takes a disipline that some of us can find hard.
Manage your Documentation
This is where we took many of the methods and techniques developed in the previous stages and applied them to the documentation system. The documentation tree was placed under CVS and commit-info mails were sent when ever changes were made. A meta package heanet-docs-toolkit was developed which provides all of the neccessary tools needed to build the docmentation.
Once this was done it was a simple process to write a Makefile that could with one command from any user validate,build & publish the output to the staging area on the server. This allowed members of the admin team to provide documentation direct without the editor having to mark it all up themselves. It also allowed minor modifications and corrections to be made in a simple fashion and maintain full audit trail of changes made.
© 2003 Colm MacCárthaigh & Colin Whittaker
