The SDSS has over 1 million lines of software, which is developed by many of its collaborators at different institutions. Use of the Web allows all of our collaborators to view our current documentation without taking delivery of the actual software.
SDSS software is not monolithic, but rather consists of many ``products,'' each with its own independent set of source files and documentation. Since products may have developers from several collaboration sites, the RCVS ( Remote extension of Concurrent Versions System) code management tool [4] is utilized to coordinate modifications.
RCVS permits people around the world to modify code, and its associated documentation, locally. Users ``check out'' a copy of a product to a local work area. They modify the code and documentation, compile it, debug it, and then ``commit'' those changes back into the RCVS repository. That makes those changes available to the rest of the collaboration.
The use of RCVS permits collaboration contributors to easily add material. They can also modify and correct documentation, promoting improved dissemination of accurate information because of the Web's ability to provide immediate access to the latest documentation.
Initially, all documentation was written directly in HTML. Recently however, there has been an effort to incorporate HTML directly into the software source code, thus avoiding duplicity of documentation and reducing maintenance. It was our goal to adequately document software routines and their parameters/prototypes. Since much of our coding conformed to a particular style of commenting, our efforts to incorporate HTML were hastened by creating a utility to automatically extract appropriate sections of code (such as routine prototypes) and build HTML.
URLs fixed to hardwired paths based on a product version is a concern. Since our coding standards restrict a product's HTML documentation to a single directory, relative URLs are used. For cross-product references, server configuration file mappings are available for each SDSS software product. This allows URLs to contain only the product name, void of any version specifics. As new product versions are developed, only the mappings in the configuration file need be changed. Naturally this means only the latest set of documentation is visible through our servers, but fortunately this is sufficient for our needs. Older versions can still be viewed by opening files locally with a browser.
Currently the server configuration file is managed by hand, but plans are in the works to automate the process, so whenever a new version of our software is produced, the configuration file is updated and reread automatically.
As indicated, our primary goal concerning documentation of our software is to produce descriptions of all user callable subroutines defined in the product libraries. As such, indices and search capabilities are a useful part of our documentation. For our needs, a general text search capability was not required. We found it adequate to simply search among all defined HTML anchors (<A NAME ...>) and title tags (<TITLE ...>). Thus, a simple script was developed to perform both the searches and to generate indices.
Since our software is destined to be run on a wide variety of UNIX-based platforms, our quality control mechanism routinely compiles our software on all supported systems. Compilation messages are filtered such that messages needing attention pass through and are incorporated into an HTML report. This hypertext report allows quality control personnel to view lists of messages sorted by operating system or source file by following appropriate links. In addition, the modification history of any of the offending source can be accessed since the script also interacts with the RCVS utility.
The Web is used as a means to track product bug reports and their status. The publicly visible bug list lets people know about problems as they are discovered. Rather than burden users with details, the list is a summary of the problems; details can be gotten by following links.
Finally, an HTML to LaTeX converter is used to generate printable documentation.