Greetings, all,
I've extended the *.docbook.def.xml extension point definition file to
allow people to indicate the author(s) associated with any chapter or
section of the documentation, and then edited these files to take my best
guess at the authorship for the existing documentation set. Authorship
info is now displayed in two places in the docbook. First, the authors are
listed on the title page:
<http://hackydev.ics.hawaii.edu/hackyDevSite/external/docbook/index.html>
And there is also a reference guide chapter that lists each author and
links to the chapters/sections that they authored/co-authored:
<http://hackydev.ics.hawaii.edu/hackyDevSite/external/docbook/ch15.html>
If you've contributed to the writing of one or more docbook files and are
not credited, please let me know and I will fix it (or, just go in and edit
the corresponding *.docbook.def.xml file yourself.)
The not-so-subtle reason for this particular enhancement is that I would
like everyone to get more involved in documentation writing starting with
the next release cycle. There are lots of important chapters that are best
written by the authors of the corresponding functionality. For example:
- How to implement reduction functions (Developer Guide, Cedric)
- Reduction functions (Reference Guide, Cedric)
- How to perform sequence analysis using SDSA (Developer Guide, Hongbing)
- Quality management using Priority Ranked Inspection (User Guide, Aaron)
- How to implement Priority Rankings and Priority Indicators (Developer
Guide, Aaron)
- Priority Measures (Reference Guide, Aaron)
- Priority Rankings (Reference Guide, Aaron)
- Managing Experiments (Administrator Guide, Mike)
- Understanding HPCS software development (User Guide, Mike)
- Writing installers (Developer Guide, Julie/Austen)
Not to mention several critical chapters still on my plate:
- How to write docbook documentation (Developer Guide, Philip)
- How to implement sensors (Developer Guide, Philip)
- How to implement commands (Developer Guide, Philip)
- How to write test cases using the Hackystat test framework (Developer
Guide, Philip)
- The common administrative commands (Administrator Guide, Philip)
And there's a bunch more of somewhat lesser priority!
Of course, before anyone can get started on this, I need to write the
developer guide chapter on docbook documentation, and my recent hacks (such
as the authorship stuff above) has resulted from my looking forward to this
chapter and realizing what needs to be enhanced prior to writing it.
As I've worked on the Hackystat documentation framework, the metaphor of a
partially sunken ship comes to mind. For the past five years, we've been
building and refining what has become a complex piece of technology, and
unfortunately our documentation has not kept pace with the development.
The result is something like a very cool ship which is mostly underwater
and thus not visible to observers. With each chapter of the documentation
framework, we're metaphorically hoisting the ship out of the water, making
a little bit more of it visible to the outside world.
Like any ship that actually floats, a significant part of it will always be
under water, and that's true for our documentation as well. For example, I
don't expect that we will ever write a chapter on the parsing technology
for the telemetry language; that's too low level, and if you want to go
there, then Use The Source, Luke. The scope of our user and administrator
guides is to explain what users and administrators need to know to utilize
the external interface of the system to support their software measurement
and analysis needs. The scope of the developer guide is to explain what
developers need to know to enhance the system using its defined extension
points. (Which is why I put the time into developing the reference guide
chapter on extension points!) So, while we still have a lot more to write,
it's not going to go on forever; there is a tunnel and a light at the end
of it.
Cheers,
Philip
