Documentation System

Ronald J. Maddalena and Carl Bignell

I. Introduction

The GBT is more versatile and, therefore, more complicated than most other single dish telescopes. The astronomers who will use the GBT will come from many fields, not just those trained in radio astronomy, and will require appropriate documentation before and during their use of the telescope. Support staff will need speedy access to a wide range of documentation for debugging problems, running system tests, and so forth. Without a proper documentation system and series of policies on documentation, the GBT might be a very challenging telescope for its users and support staff. We hope that the plans described in the following sections will produce a documentation system that will mitigate the difficulties of using the GBT.

II. Expected Users

We expect a wide range of users, both in-house and external, will use the documentation for the GBT. The in-house users will encompass telescope operators, engineers, programmers, and other support staff like the friends of the telescope and members of the scientific support staff. Outside users of the documentation will include astronomers, visitors, and maybe even the general public.

We anticipate that each class of user might require documentation written explicitly to fulfil the needs of that class. Most often the person assigned to write the documentation for a particular class will be a domain expert from the class of user for which the documentation is aimed. For example, operators will be writing documentation on telescope interfaces for their fellow operators while astronomers will be writing documentation on interfaces for other astronomers.

III. Goals

The GBT documentation system must satisfy a wide range of goals. The ranking of these goals is somewhat up for debate and some might not be reachable because of cost constraints. Our top priority goals are:

• Easy access for all classes of users,
• Automated generation of hard copy and electronic on-line documentation from the same source document,
• Electronic documentation available across various computer architectures,
• Must include both text and images,
• Low cost to generate and maintain,
• Easy generation of high-quality indices and table of contents,
• Sufficient cross referencing,
• Timely distribution of updates,
• Uniformity of style and format,
• Easily searched by key words,
• Generation and maintenance of documentation can be distributed among different writers,
• Quality control at a low cost.

 

IV. Expected Content

The full extent of the documentation will not be known for some time but we anticipate we will need documentation for staff that includes:

• Operations manuals
• Training manuals
• Instrumentation documentation
• Policy manuals
• Safety manuals.

A few of these documents have already been started and, in section VI we give dates for their expected completion.

Likewise, Cecilia Barnbaum continues to write some of the documentation for astronomers. This includes:

• User's manuals
• Tutorials
• Instrument specifications

In total, the GBT documentation in all anticipated categories might exceed 10,000 pages.

V. Solution

Our goals and the expected range of the GBT documentation have led us to a particular solution and technology. Today there exists a few commercially available software packages that claim to provide the appropriate tools for a task of this size and we are extensively evaluating two such systems: RoboHelp (eHelp Corporation; http://www.ehelp.com) and ForeHelp (ForeFront, Inc., http://www.forehelp.com/). We will make a decision which package we will commit to by the start of summer.

Both these packages provide a WYSIWYG editor for producing documentation that can be presented to the user in various formats. The formats of interest to us are web-based hypermedia, paper copies, and on-line help files, all of which are generated from the same documentation file. The creation of indices and table of contents is simplified by these packages. For web-based documentation, the generated web pages use JavaScripts for displaying and linking table of contents entries, indices, and searchable key word lists. This makes the documentation look and feel very similar to that of standard help files on a Windows9x/NT system. Figure 1 is a screen dump of what the web-based documentation might look like.

The packages also provide the means to help manage a large documentation project plus ensure all documentation follows an accepted style. For example, each system provides a to-do list for each document. We can also use these systems to enforce certain policy decisions we will need to make concerning the generation and maintenance of documentation. We are good ways along in formulating these policy issues and we have already decided that:

• Multiple domain experts or users can create and revise documentation concurrently.
• There will be a central person for checking a created/revised document before acceptance into the system. This person will most likely be from telescope operations or the GBT scientific support staff.
• All writers will adhere to a single style and format that may closely follows, for example, the NRAO's new web style.

The extent of the documentation requires a strong commitment from the NRAO. We anticipate that two operators will spend up to 20% of their time on writing and revising documentation. Similar efforts will be required from astronomers, engineers, and programmers.

VI. Time Line

Many aspects of the GBT documentation are well under way. Unfortunately, most of the existing documentation has been written by individuals using different styles and technologies. Once policies have been formulated, the existing documentation must be converted into the above system and edited to adhere to the standard style. We are still in the early steps of this process and have but preliminary guesses as to the time required to achieve our goal. We hope to have a first draft of the astronomer's documentation by September 2000 with first drafts of engineering, operations, and programming completed by the end of 2000.