Version 1.9 Build 1556

News	FAQ
Search	Home

Next: Example of In-line Documentation Markup Up: NOTE 243 - XML-based Documentation for AIPS++ Previous: Implementation Plan

Conclusions

The most important aim of the framework described here is to make it easier for developers to create and deliver documentation that is high-quality not only in presentation but in content. Employing the widely-used DocBook XML markup has the potential for providing greater flexibility and reliability in formatting and presenting our expository documents than L^ATEX. The use of the LyX editor can greatly reduce the overhead of learning to use DocBook markup and will hopefully encourage contributions from people outside the core development team.

The proposed system for in-lined documentation of Glish code will make it much easier to create complete, well-organized descriptions of tools and functions. Specifically, the simple markup syntax and the ability to extract some information automatically from the glish code itself reduces the amount the developer has to type. Furthermore, in-lined documentation encourages the practice of developing documentation simultaneously with implementation: simple descriptions can be entered when the tool is first prototyped; details can be added as the implementation crystalizes; once the interface is set, the function parameters can be described and the necessary metadata for the Tool Manager, provided; examples can be added during testing; and finally, as the tool is tweaked and debugged, the changes can be reflected right away into the documentation. The structure can encourage completeness, and the use of a validation tool can help ensure that all necessary infomation has been encoded.

Despite our best efforts toward software solutions, there is no cure for the lazy programmer in all of us. Thus, the key to making any documentation framework successful is in the conscientious efforts of developers. A style guide is important for advising us on how to make the best of the system. At the same time, the documentation system can make the best of our efforts by providing tools that make it easier pass our expertise onto users.

Next: Example of In-line Documentation Markup Up: NOTE 243 - XML-based Documentation for AIPS++ Previous: Implementation Plan Contents