Ronald J. Maddalena and Carl Bignell
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.
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:
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:
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:
In total, the GBT documentation in all anticipated categories might exceed 10,000 pages.
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.
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:
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.