The documentation for the Hackystat Framework is organized into a four volume set consisting of the User, Administrator, Developer, and Reference Guides. The User Guide contains information on how to install and use sensors and run analyses on collected data from an installed Hackystat server. The Administrator Guide contains information on how to download, install, and administer a Hackystat server. The Developer Guide contains information on how to design and implement new sensors, sensor data types, applications, and other "extension points" in order to build new Hackystat configurations specialized to new domains. The Reference Guide contains chapters that document the available instances of each type of "extension point" in a Hackystat configuration, such as the available sensors, sensor data types, reduction functions, and so forth.

The purpose of this chapter is to explain how a developer adds new documentation to one or more of the above Guides. This involves understanding several concepts. First, you need to understand the architecture of the Hackystat documentation framework, and how the four volumes are constructed when a specific Hackystat configuration is built. Second, you need to understand how to write documentation in the appropriate XML format. Finally, you need to know how to invoke the documentation generation tools, and how to debug your documentation "code" when things go wrong.

The Hackystat documentation is based on DocBook, which is an XML-based, presentation-independent representation for documentation. We chose DocBook because writing the documentation in XML makes it relatively easy to programmatically manipulate the content. For example, we can combine together documentation "fragments" from different Hackystat modules to produce a customized documentation set for each configuration of the system. DocBook also allows us to generate different presentations of the documentation, such as HTML or PDF. The downside is that writing DocBook-compliant XML is fairly painful, and we'll discuss that particular agony in more detail later in this chapter.