The previous section overviews the process of developing new sections for the Reference Guide, which is the most common form of documentation added to the system. For example, most additions to the hackySdt and hackySensor subsystems require Reference Guide documentation.
However, more sophisticated extensions to the system, such as the modules in the hackyApp and hackyCore subsystems, might require explicit documentation oriented toward one or more of the users, developers, and/or administrators. For example, the hackyCore_Telemetry subsystem implements an analysis approach called Software Project Telemetry. Users can best learn how to use Telemetry by one or more chapters in the User Guide. As the Telemetry language can be customized by developers, the Developer Guide can include one or more chapters explaining how to do this.
Writing documentation for the User, Administrator, and Developer Guide is very similar to the way you write documentation for the Reference Guide. The major differences are that the top-level tag will be <chapter>, not <section>, and you might decide to locate the docbook directory at the top-level of your module, not nested inside the directory structure at the location where the extension point is implemented. Finally, the XML tags used in the docbook definition file are slightly different.
To illustrate the main issues in defining a chapter, we'll use the hackyDoc_NewModule example module.
The easiest way to explain how to add a new User, Developer, or Administrator Guide chapter is to work through an example. We'll use the "hackyDoc_NewModule.zip" package referenced in Chapter 14, Creating new Hackystat modules. If you have not already done so, please download and install the hackyDoc_NewModule package following the instructions in this chapter.
Once you have installed the hackyDoc_NewModule module into your local configuration, you should check to make sure the documentation can be generated correctly by running "ant hackyCore_Build.buildDocBook". After executing that command, you should be able to view in a browser the file hackyCore_Build/build/war/docbook/index.html. Figure 18.2, “ The table of contents showing the NewModule chapter ” illustrates the NewModule chapter entry.
As you can see, Chapter 11 contains the documentation for the NewModule "application". Let's now explore how the hackyDoc_NewModule module provided the information needed to produce this documentation section.
As with all Hackystat documentation, you must provide the files inside a "docbook" directory. In the case of documentation chapters, this directory is typically located at the top-level of the module implementing the features described in the documentation. Example 18.7, “Location of the docbook/ directory in hackyDoc_NewModule” illustrates this organization.
Example 18.7. Location of the docbook/ directory in hackyDoc_NewModule
hackyDoc_NewModule/
docbook/
devguide/
hackyDoc_NewModule.devguide.docbook.def.xml
hackyDoc_NewModule.devguide.docbook.xml
As you can see, the docbook directory occurs at the top-level of this module. Inside this directory is another directory, called "devguide", which is used to hold the documentation files associated with the chapter (or even chapters) to be placed in the Developer Guide. In the case of hackyDoc_NewModule, this is the only chapter included in the module, but other modules might have "userguide" and "adminguide" subdirectories as well.
The build system does not require a specific subdirectory structure inside the "docbook" directory; it will recursively search all nested subdirectories in every "docbook" directory for documentation files. However, it is often convenient to organize the contents of a module-level docbook directory into subdirectories when the module defines more than one chapter.
Example 18.8, “hackyDoc_NewModule.devguide.sdt.docbook.def.xml” illustrates the docbook definition file for the NewModule documentation.
Example 18.8. hackyDoc_NewModule.devguide.sdt.docbook.def.xml
<hackydocbook>
<chapter guide="Developer"
fileName="hackyDoc_NewModule.devguide.docbook.xml"
rank="100.0"/>
</hackydocbook>
As with all of the docbook definition files, the top-level tag is <hackydocbook>. In the case of chapter definitions, the tag inside the top-level tag is <chapter>, which supports three attributes.
The first attribute, "guide", takes a string that must be one of "User", "Developer", or "Administrator", and indicates the Guide in which this chapter will appear.
The second attribute, "rank", is a floating point number that is used by the build system to order the chapters within a Guide.
The third attribute, "fileName", is a string that names the file containing the contents of this chapter.
Example 18.9, “hackyDoc_NewModule.devguide.docbook.xml” illustrates the docbook.xml file for the NewModule documentation.
Example 18.9. hackyDoc_NewModule.devguide.docbook.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC
"-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
"http://www.cs.put.poznan.pl/dweiss/dtd/dweiss-docbook-extensions.dtd" [
<!ENTITY % isopub SYSTEM "iso-pub.ent">
%isopub;
<!ENTITY % local SYSTEM "local-entities.ent">
%local;
]>
<chapter id="ch:hackyDoc_NewModule.developerguide">
<title>[hackyDoc_NewModule] Sample Chapter</title>
<para>
If this was a real docbook documentation chapter, its purpose would be to
explain the design and implementation of the hackyDoc_NewModule module for
enhancement and extension by other developers.
</para>
<para>
However, this is not a real docbook documentation chapter; it's purpose is
actually to show simple examples of the files and their locations in a Hackystat module.
</para>
</chapter>
A documentation chapter begins with the same file header used for a section, and has the top-level tag <chapter>. The contents of the chapter depend upon the Guide that it appears in. User Guide chapters should provide details appropriate for end-user application, Administrator Guide chapters should provide details appropriate for installation and configuration, and Developer Guide chapters should provide details appropriate for enhancement and extension. Of course, a single module can provide more than one of these chapters, depending upon how many of these areas require documentation.