Linda StewartTechnical Writer Instrument Approach Procedures Automation Team Federal Aviation Administration Mike Monroney Aeronautical Center 6500 S. MacArthur, AMI-200C Oklahoma City, OK 73125-4943 (405) 721-1901 Home (405) 954-3394 Work (405) 720-8088 Fax firstname.lastname@example.org
This paper discusses issues encountered by a small, but highly specialized programming team in converting documentation to online hypertext format while simultaneously porting the entire project to a new platform into the virtual file structure of ClearCase, a versioning software. The online documentation versioning issue dominated an entire series of meetings. The final consensus was to version the documentation which was only the beginning of a series of unique challenges.
The decision to version the software presented a series of questions and issues that remain mostly unanswered and unaddressed. The bulk of major issues at present is not a problem, but as the software porting issues are solved and the first version of the software is formally released, emphasis will switch to resolving these issues. At present, our developers and users are resigned to be content with the present state of things, but watch the industry in general with anticipation for many of these issues to be resolved by research and development, making tools available to smaller businesses and projects lacking sufficient personnel to develop their own.
The Instrument Approach Procedures Automation (IAPA) team develops and maintains software that calculates instrument approach procedures for airports. The system is being ported from Data General minis to a network of 120+ Silicon Graphics Indigo2 workstations.
As technical writer for the team, my initial task was to write man pages for existing routines and prepare to rewrite portions of the User Manual. After discovering Mosaic and the World Wide Web, the team decided to use HTML to create a hypertext system to accommodate programmer/developer and enduser documentation, training materials, online help, procedures manuals and various other documentation. Mosaic and HTML proved to be effective tools for the size and nature of our project and documentation.
The history of the software and its development and evolution through the years created the need for versioning capabilities. Multiple programmers worked on various portions of code over a period of many years with notoriously scant documentation. The versioning software desired would force developer accountability and create an audit trail for future developers as well as maintain versions of the software.
The versioning issue was addressed by the Silicon Graphics version control and configuration management system called CASEVision/ClearCase (TM). ClearCase presented the capability of managing multiple versions of evolving software and related documentation and database information, tracking versions used in software builds, performing builds of individual programs or entire releases according to user-defined version specifications and enforcing site-specific development policies.
Other tools used in relation to the hypertext system include:
I feel the following are issues to address in striving for an efficient versioning system that would support the elusive sophisticated, widely distributed, open and interactive hypertext system:
Linda Stewart is a Technical Writer for the United States Federal Aviation Administration working with the Instrument Approach Procedures Automation team at the Mike Monroney Aeronautical Center in Oklahoma City, OK. As sole tech writer/documentation manager for this group of eleven programmers/developers, she is currently involved in the design and implementation of their online hypertext documentation system on Silicon Graphics Indigo2 network using HTML and Mosaic. All documentation including training manuals, user manuals, help text, man pages, meeting notes and various other documentation is being converted to online format. Future projects include converting to hypertext three official government manuals used by procedure specialists all over the world.
Linda is an accomplished public speaker and has a total of 15 years small business/small project management experience in the computer industry.