An imagemap of NCSA's garden of architectures greets the Ops Documentation user...
Mike Pingleton and Tom Fischer
National Center for Supercomputing Applications
Over the past several years, the Operations Team at the National Center for Supercomputing Applications (NCSA) has seen its responsibilities grow from taking care of two Cray supercomputers and a mass storage system, to overseeing the operations and basic system administration of a dozen different computing architectures ranging from several hundred Macintosh workstations to a 512-node TMC CM-5, in addition to providing a HelpDesk facility that services both NCSA's staff and national user community. The growth and increased complexity of our team's responsibilities quickly overwhelmed the effectiveness of our documentation set, which consisted of paper documents in ring binders, and their electronic originals kept on an AppleShare Server, all in Microsoft Word format. This situation, coupled with the added pressure of a reduced staffing level, forced us to look for a documentation system that was easily accessible by Operations staff, was easily updated, would allow for quick and simple additions of new documents, and at the same time was thorough and comprehensive.
Our search led us to devise and implement a Mosaic/WWW Documentation Set consisting of hundreds of pages of easily maintained hypertext documents, as well as a system of tracking daily and monthly duties that utilizes Mosaic's fill-out forms feature. We also saw advantages to creating a HelpDesk Interface which serves timely system-specific information and FAQ files, which promises to have a large Center-wide impact as more staff utilize Mosaic.
This paper discusses the strategies we used in creating the Documentation set, check-lists, and HelpDesk Interface, as well as the advantages inherent in these information services, for both end-users and maintainers.
Only five years ago, the Operations Team's main responsibility was comprised of watching over two Cray Supercomputers, and performing operational tasks with the mass storage system which was used in conjunction with the Crays. Documentation for these two tasks was made up of two three-ring binders: one for mass storage, and one for Cray. Operations procedures were fairly static, and the documentation sets seldom needed updating. The master copies of both sets were in a Macintosh Microsoft Word format.
Three years ago, NCSA started adding to its cache of computers with the acquisition of two Convex systems, two Thinking Machines, Inc. massively parallel computers, IBM RS6000s, etc. The Operations Teams' responsibilities expanded to included the administration and operation of many of the new systems, and the team's documentation set quickly became obselete. An attempt was made to keep documentation in Microsoft Word format on an AppleShare Server. However, this was a time-consuming and cumbersome approach, because most new procedural documents arrived to Operations in the form of email, and each message would have to be converted over to Word format. Also, the documents could only be accessed throught the use of a Macintosh workstation, which weren't always conveniently located when documentation was needed and wasn't on hand in hard copy.
Over the course of three weeks in April of this year, NCSA Ops documentation was converted to an HTML format, and with the use of NCSA Mosaic, the new documentation became an integral tool that is used constantly by the team.
Documentation is accessed through a general "table of contents" page, consisting of several hypertext links to more specialized hypertext subtables of contents. The top table also contains an image-map, containing images of all NCSA architectures or systems, as well as key words, with each image or word mapped to bring up a subtable. The subtables are divided by architecture, system type, miscellaneous, etc. Items or topics that fall under several categories are hyperlinked from each applicable subtable. The Operations Documentation Set is currently consists of over 300 individual documentation topics.
An imagemap of NCSA's garden of architectures greets the Ops Documentation user...
The documentation set is served by an Operations group maintained HTTP server which is configured to allow only Operations systems access to the documents.
A major advantage of this approach to documentation is the ease and speed of
document creation and maintenance. At worst, the document creator need
only to know how to use the <pre> markup command to
create a readable html document. E-mail, PostScript, and MS Word files can
also be quickly converted to html format using various conversion programs.
Spreadsheets, charts, and graphs are converted to gif files and then inlined
into the documents. Only a few simple format guidelines ensure reasonable
uniformity in appearance.
Another advantage to using an html/Mosaic documentation approach lies in the
ease of accessibility of the document. Documents can now be viewed on a
variety of systems (For our needs, this is mainly Macintosh and X-Window
systems). This ease of accessibility allows us to pull up documentation
wherever we may need it, usually right onto the console window of the system
that we are working on. And, in the increasingly rare instances where we may
find ourselves without any kind of GUI interface, the lynx browser
has come in handy.
Documentation residing on web-servers outside of NCSA that is of interest to the Operations team has also been linked into the Ops documentation. The ease of access across the WWW enables us to quickly access an AFS FAQ, gopher-based Convex bug reports, etc., through the use of Mosaic.
Using multiple windows enables cutting and pasting from the document to the command line for added efficiency. Using multiple windows is also an effective technique for creating a new document in a matter of minutes. The authors were able to convert the entire Operations Documentation set, more than two hundred individual documents, in less than three weeks.
Soon to be added to the documentation set are shift checklists. These
checklists take advantage of Mosaic's forms functionality to
monitor the daily, weekly, and monthly tasks of each work shift. The
checklist is made up of button-based options, as well as fields for entering
comments, and a scrolling list of relevant documentation topics. The
forms are driven by perl CGI scripts. The checklist data is dumped to a file,
and can be accessed later through a different search form.
Forms-based checklists provide a reliable method of keeping track of daily,
weekly, and monthly tasks.
Finally, Mosaic allows all of the documents and checklists to be saved or printed in different formats with ease.
The Operations group at NCSA is also responsible for staffing the NCSA HelpDesk, a first-line troubleshooting operation for the Center. Users interface with HelpDesk staff through telephone contact and email. The percentage of the NCSA comuunity using Mosaic is increasing daily, so it seemed like a logical step to develop a Mosaic interface to the HelpDesk, giving users yet another option for receiving assistance or answers to queries. The HelpDesk Page provides a number of services in this manner.
From the Mosaic HelpDesk page, users can send mail to the HelpDesk, using the provided mail form. The text areas in the mail form allow users to send a description of their problem or query, along with their name, login name, building, room number, and telephone number. Using this form not only insures that the note goes to the proper email address, but also helps to provide HelpDesk staff with all the pertinent information needed to quickly solve the user's problem or answer a question.
The HelpDesk Mail-in form prompts users for pertinent information so that
their problems can be quickly solved by HelpDesk staff.
Users can also access FAQ (Frequently Asked Questions) lists, in html format, developed by the Operations Staff. FAQs are an important tool; users can get basic questions answered, freeing the HelpDesk staff to handle more complicated matters. The FAQ page references both locally-developed FAQs, and relevant FAQs located at other WWW sites.
A HelpDesk Overview Page informs users of all the services provided by the Helpdesk, hours of support, problem resolution methods, etc.
Finally, the NCSA user community can keep up to date on upcoming maintenance, downtime, and upgrades for all major systems by reading the NCSA Computing News page. By using this page, a user of multiple NCSA systems can stay current with news covering all systems by reading one WWW page with Mosaic, instead of logging into each system to reads each individual message-of-the-day, etc. From this page, the user can reference news items for each system, informing her of software upgrades, system-specific procedural changes, etc.
The NCSA Computing News page centralizes the news of all major systems,
simplifying information access for users.