Getting Started

Documentation

Glish

Learn More

Programming

Contact Us

Version 1.9 Build 1556

News	FAQ
Search	Home

Subsections

• Current Principles and Framework
• Room for Improvement
  • General
    • Documentation build system is fragile and difficult to maintain.
    • L^ATEX is sufficiently complex as to make creating documentation non-trivial.
    • It is difficult to adjust the presentation of documentation.
  • Reference Manual
    • Process for creating module documentation is laborious
    • Structure of function description makes it hard to find information related to specific parameters.
    • The presentation of the parameter description discourages complete descriptions.
• The Case for a New Approach

Introduction: The Current State of AIPS++ Documentation

Current Principles and Framework

Note 215 describes the current framework of documentation in AIPS++. In general, there are three types of documentation in AIPS++:

• Expository documents (e.g. Getting Started, Getting Results, Notes, Memos), usually in L^ATEX format;

• Glish tool documentation (i.e. the User Reference Manual);

• C++ Class documentation, using SGML markup in-lined into C++ header files and extracted with cxx2html.

The first two types are the most important to users. The Getting * documents are meant to instruct users in the general skills and approaches used to process data in AIPS++. It's expected that users will read large parts of it in whole. The Reference Manual, on the other hand, is meant primarily as a definitive guide to specific tools and functions; users consult this document to locate specific bits of information.

The current documentation framework is based (in part) on the following principles:

1.

Users must have access to documentation on-line.

2.

Users must be able to print out documentation in a high-quality form.

3.

It must be possible to build the documentation anywhere AIPS++ is installed.

4.

The above features are be enabled via three ``cornerstone'' formats: L^ATEX, HTML, and PostScript.

L^ATEX is the source format for the documents aimed at end users. In particular, developers use specialized macros to markup components of the documentation that makes up the Reference Manual.

Room for Improvement

This section lists some of the problems with the current system which this study hopes to address.

General

Documentation build system is fragile and difficult to maintain.

Because the system depends on complex, external packages which must be installed seperately (L^ATEX and L^ATEX2HTML), setting up the system up to build documentation automatically is not easy. UIUC does not build documentation locally because of the problems we've had trying to configure the system. Instead, we import the built documentation from Socorro.

L^ATEX2HTML is certainly the weakest link in the documentation system. Since importing docs from Socorro, we have found that the HTML version of the Reference Manual regularly does not format argument lists properly. Problems formatting equations and images are common but often go undetected by the make system.

L^ATEX is sufficiently complex as to make creating documentation non-trivial.

Many of the formatting problems that currently exist can be traced to mark-up errors on the part of the author. Common errors like the ``missing brace'' can have drastic effects on the formatting. It's also important to check the translation to HTML; a document that processes fine with L^ATEX can be mangled in a variety of ways when passed through L^ATEX2HTML. The AIPS++ system does provide developers with tools checking their documentation (make file.dvi and, more recently make file.html). Nevertheless, formatting errors are still quite common. This may be largely due to developer laziness; however, it may reflect in part on the difficulty in getting the tools to work properly.

This author's own difficulties are primarily due to the fact that the UIUC installation is not properly configured to build the documentation. However, I was also unable to process my documentation on tarzan at the AOC. If this is a common experience among developers, then the supporting tools are not sufficiently helpful in checking our documents.

It is difficult to adjust the presentation of documentation.

This is due to the inherent complexities of L^ATEX and L^ATEX2HTML. Significant skill and experience is needed to fiddle with L^ATEX style files to adjust the document layout. It is arguably even more difficult to adapt L^ATEX2HTML to variations in presentation. This barrier of complexity not only discourages experimenting with presentation but also the resolution of formatting problems.

As an example of experimenting with presentation, some developers have expressed a preference for layouts that maximize the amount of content that can be viewed at once. This might call for smaller margins in the hardcopy version. It might also call for a re-arrangement of information presented in a Reference Manual page. Small changes as these could have big effects on the documentation's user-friendliness; thus, it would helpful if it were easier to modify the layout and try new presentations.

Reference Manual

The overall organization of the Reference Manual, with its hierarchy of packages, modules, and tools, is good. A significant portion (if not the majority) of the content is of good quality. Nevertheless, it can still be difficult to find specific information on how to use specific tools and functions. This is not always due to a paucity of words, but often due to structure.

Process for creating module documentation is laborious

After creating a tool implementation, the developer must create two separate files (tool.help and tool_meta.g), each to some extent containing redundant information both between them and the Glish source code. As separate files and with different formats, they are not conducive to being developed in parallel with the software. Thus, they are usually done as a separate chore, after the implementation. This can tend to discourage completeness, particularly in describing allowed values to functions or caveats to use special circumstances; this is because, since the developer is somewhat more removed from the inner workings of the code, including this information is more difficult.

Structure of function description makes it hard to find information related to specific parameters.

It is common for a user to want to discover the meaning and use of a specific parameter. The obvious place to look is the table of function parameters; however, this contains limited information (see next item). For additional details, the user must sift through the general function description. (New users may not know to expect additional information to be hidden there.) It would be better if all the information related to a parameter could be found in one, easy-to-find place. Repetition of this information in the general description is fine and often useful when describing the role of the most important parameters in the overall use of the function.

The presentation of the parameter description discourages complete descriptions.

Function parameters are listed and described in a structured table. In the HTML version of the manual, this table is quite narrow (perhaps one half the width of a typical browser window), so very little information can be contained in this table before it becomes difficult to read. As a result, developers must go to the effort of including more complete information in the general description of the function, which sometimes does not happen. Thus, parameter descriptions are limited to a single clause or sentence, and default and allowed values sometimes go undescribed. And because the content of the general description section is unstructured, the fact that this information is missing goes unnoticed (except by those specifically looking for it).

The Case for a New Approach

It is worth noting that a L^ATEX-based system can probably be made to work and our overall system improved for users with additional effort, perhaps even comparable to the effort of converting to a new framework.¹ However, the inherent complexities of L^ATEX and L^ATEX2HTML discourages us from improving and enriching the system. In contrast, an XML-based framework offers new possibilities for developing documentation features (e.g. two-way links, automated indexing, context-based help, ASCII displays for Glish, integration with Tool Manager metadata).

More important than new capabilities, a new approach to documentation offers the opportunity to make authoring and delivering documentation easier. This note posits that if this process can be made less laborious, authors will create higher quality documentation-that is, more comprehensive and with the necessary information where users can easily find it. Indeed, substantial improvement in documentation quality for the end user must be a requirement for any substantial change in the documentation system.