Position on Versioning in Hypertext Systems

Linda Stewart
Technical 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


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 Project


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 Tools:

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.

ClearCase is a solution only for the budgets that can monetarily afford its power. Requires extra steps and time in the work flow.

Other tools used in relation to the hypertext system include:

The Issues:

Indexing appears to be a major challenge for any hypertext system whether distributed or open. With the decision to version the online documentation, the indexing issue expanded from simply needing effective, intuitive search engines and resulting documents, to needing to search selected versions as well as current documents. ClearCase searches the virtual file structure, but is available only to hosts running the software.
Forms and scripts related to documentation also present challenges by the need to maintain availability to their corresponding versions. ClearCase provides this ability but again with the limitation of availability to only the hosts running the software.
The personal annotation capability is widely used in this system. Group annotation is the greatest need in our development system since it is so dependent on user/development interface and interaction. I designed a script that used a form to allow group annotations that wrote the output directly back to the displayed file, then redisplayed it. Situations already exist that would indicate a possible need for access to various versions of annotations.
File Structure and Naming Conventions
File structure and naming conventions present the biggest problems when attempting to cross platforms, e.g. from UNIX to DOS. We chose extended naming conventions (even though this does not meet ISO standards) since there is no intention to cross platforms, but those intent on distributing systems have to consider this. I am unsure of the implications of these naming conventions on the future of our online documentation and subsequent versions.
Human Factors
Perhaps human factors such as procedures and permissions are questionable as to their relation to versioning in a hypertext system, however, the most powerful system loses its effectiveness without proper planning, use and management. Every meeting dealing with the issues of versioning the hypertext system also came full circle to "who?" Considering these factors can only be beneficial to the outcome of all research and development in this area.
Compatibility between browsers, editors, etc. appears to be a major issue. Making sure the applications are rich in the backwards compatibility area is a must. At present we maintain all old applications used by the versions as part of their release, but this obviously uses valuable disk space.
Our group is attempting to link to single documents from training guides, user manuals, help files and meeting notes. Once again, this is not a problem for those hosts running ClearCase. The need to copy the released version to a standard file structure duplicates the entire web and once again, devours space.


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:

About the Author

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.