Greetings, all, First, after working on the Telemetry documentation for the past couple of weeks, I wanted to publically congratulate Cedric on all of his hard work over the past two years on this mechanism. The addition of Y-Axis and Filter Functions to the existing Reduction Functions, Streams, Charts, and Reports creates what I consider to be a very elegant, sophisticated, and expressive language for representation and understanding changes in software engineering metric values over time. I will not be at all surprised if history comes to view this as a substantial advance in the field of software metrics. An overview of the current language is available in the User Guide chapter:
<http://hackydev.ics.hawaii.edu/hackyDevSite/external/docbook/ch05.html> Second, I've also done a certain amount of refactoring of the docbook documentation in general in order to address some scale-related issues. When the docbook documentation was only about 10 chapters total, it was of course easy to find things. (More accurately, it was easy to figure out whether the feature you were interested in was actually documented or not. More often than not, it wasn't yet documented!) We're now up to 27 chapters, across four volumes, with many more on the way. Moreover, telemetry-related material now contributes 5 chapters (2 in the user guide, one in the developer guide, and 2 in the reference guide); TDD-related material currently contributes 2 chapters with more to come; and Mike has some HPC-related chapters under development. Although some of this complexity will be managed by the use of configurations, which reduces the installed documentation set to only those chapters relevent to the installed modules, I am realizing that we still need to establish conventions to help users navigate across the sea of documentation that we are building. My proposal at this point is quite simple: for modules that result in multiple related documentation chapters, we should establish a common prefix for the chapter title, in order to help the user immediately identify the chapter as belonging to a certain system or functionality family. The current table of contents illustrates this approach: <http://hackydev.ics.hawaii.edu/hackyDevSite/external/docbook/index.html> What I've done is name all of the chapters related to telemetry with the prefix "Software Project Telemetry:", so we have: 5. Software Project Telemetry: Understanding the dynamics of software development 6. Software Project Telemetry: A "Control Center" for client-side telemetry monitoring 21. Software Project Telemetry: Defining Reduction Functions and Filter Functions 25. Software Project Telemetry: Filter Functions 26. Software Project Telemetry: Reduction Functions as well as the use of "Zorro:" for the TDD stuff: 7. Zorro: Evaluating Test-Driven Development performance 10. Zorro: Guidelines for performing validation studies I think if we follow this approach, we can help the user stay oriented a bit better. At some point, for example when we get to 100 or 200 chapters, we may need to generate alternative "slices" through the docbook. For example, while we now generate four slices (User, Developer, Administrator, Reference), we could also generate a "slice" for Telemetry, which would be a docbook document containing just the five chapters listed above. The great thing about our current docbook-style documentation approach is that multiple alternative slices would be quite trivial to implement if we ever get to the point where it would appear to be useful. It is a good sign that our documentation is now confronting scalability-related issues. It means that it's finally starting to catch up to the system itself, which we've been re-designing for improved scalability over the past several years. Cheers, Philip
