The first thing to understand about the Hackystat documentation is that it must be "configurable" to the specific set of modules included in any given Hackystat configuration. To understand the motivation for this requirement, remember that Hackystat consists of over 70 modules, many of which implement specialized functionality for particular domains. If every organization using Hackystat were forced to install every single available feature of Hackystat, the system would quickly become large, sprawling, and difficult to use. To solve this problem, the Hackystat build process is organized around the concept of a "configuration", which is a subset of the total available modules that provides the functionality of interest to a certain kind of organization. Many useful configurations of Hackystat contain less than half of the total available public modules. Indeed, some organizations might build custom configurations in which they combine some publically available modules with additional private modules they have developed in-house to support their organization-specific needs.
Thus, to be useful, the Hackystat documentation system must also support configurations. As a result, instead of a single, static repository of documentation, Hackystat documentation is distributed amongst the Hackystat modules as a set of files named and structured in particular way. When a configuration is built, the documentation files associated with the modules belonging to that configuration are collected together and used to construct User, Administrator, Developer, and Reference Guides containing just the documentation appropriate to that configuration. This documentation is accessable from the Help page of the server running that configuration.
The kind of documentation provided with a module depends upon the nature of the module. For example, a module containing the definition of a sensor (such as hackySensor_Jupiter) might contain a documentation file presented as a section in the Reference Guide Chapter documenting the available Sensors for the configuration. Similarly, a module containing the definition of a sensor data type (such as hackySdt_DevEvent) might contain a documentation file presented in the Reference Guide chapter on Sensor Data Types.
Hackystat application modules might have more complex forms of documentation. For example, the hackyApp_Experiment module, which provides facilities for performing experiments with Hackystat, might contain a documentation file presented as a self-contained Chapter in the Administrator Guide, and that describes to administrators how to set up and conduct an experiment using Hackystat. The hackyApp_Pri module, which provides an extensible mechanism for priority-ranked inspection, might have several documentation files. One file might be presented as a Chapter in the User Guide, explaining to users how to employ priority-ranked inspection to decide which of their software components appears to be most in need of inspection. Another file might be presented as a Chapter in the Developer Guide, explaining to developers how to implement new "indicator" and "ranking" classes for the PRI framework in order to improve the quality of the ranking system for a particular domain of application. Finally, documentation files for each of the indicator and ranking classes available in the configuration might be presented as sections in their respective chapters of the Reference Guide.
Of course, the Hackystat "core" modules can contain documentation that spans all four of the Guides. For example, this chapter (i.e. Chapter 18, Writing documentation) is provided as a file in the hackyCore_Build module. Naturally, since every configuration of Hackystat requires the hackyCore_Build module, this chapter will be present in the Developer Guide for all configurations.
In summary, every module typically contributes one or more documentation files to one or more of the Guides. What kind of documentation a module contributes depends upon the nature of the module and what functionality it contributes. The Help page of a Hackystat server will contain links to the four volume reference guide constructed out of the modules associated with its configuration. Documentation associated with modules not included in a configuration will not appear in a Hackystat server's Help page built using that configuration.
Although there is no Hackystat server (that we know of) that is built from a configuration consisting of all publically available modules, it is nice to have access to a "complete" documentation set constructed from all public modules. We build such a documentation set each night from the latest module sources and provide links to it from the Hackystat Developer Services Server.