Using documentation as a life-cycle tool; integrating document, development tools improves quality throughout product's life - computer-aided software engineering

Software Magazine, Dec, 1992 by Mary Hanna

Integrating document, development tools improves quality throughout product's life

"I wish it could be easier. I wish I didn't have to do any documentation at all," said Paul Koenig, director of software engineering at Siemens Infusion Systems, based in Sylmar, Calif. Koenig echoes the sentiments of software developers everywhere.

During a typical project, programmers concentrate on getting the application software up and running, rather than producing a document at the end of each development phase. As a result, they usually leave the documentation to the end.

In addition to producing a document, handling the maintenance and distribution of documentation is time-consuming. Yet, a software supplier would not want the documentation effort to cause a delay in the distribution of the latest release of the software. For developers, automating the production of documentation is one answer.

Automation is only part of the solution, though. With the increased emphasis on software documentation "process," the quality of software documentation is also gaining importance. Moreover, there is growing recognition that documentation is not an end in itself. Rather, it is a tool that facilitates other life-cycle events such as maintenance, debugging and upgrading.

The integration of documentation tools with other development tools makes it possible to assemble a robust reengineering system capable of documentation, configuration management, distribution, debugging, reverse engineering and reengineering.

EMERGING TRENDS

Military and technical customers have long mandated the documentation of requirements and design. For example, the Department of Defense (DoD) requires that its software suppliers comply with the DoD standard 2167A. This standard mandates a highly formatted documentation detailing each phase of the development life cycle.

Commercial developers are now finding themselves in similar situations. "The Food and Drug Administration is getting more serious about regulating the quality of software that goes into medical instruments," said Koenig of Siemens Infusion Systems. This directly impacts a company such as Siemens, which manufactures medical electronic instruments that often contain embedded software.

Although the FDA has not yet published standards as detailed as the DoD's, forward-looking companies anticipate that regulation of the software development process is inevitable. The FDA and other commercial customers will want to determine that developers took reasonable care during the design process, and that they had the process under control.

Five major trends are emerging in the documentation management field, according to Jim Meyer, vice president of the Document Management Group at Interleaf, Inc., Waltham, Mass. These trends are:

* Unified development environments must evolve to handle the interrelationships among multivendor tools at both the macro and micro levels. "Our biggest challenge is the integration of information and documents. We need to see more frameworks that packages can plug into," said Meyer.

* Configuration control is becoming more important because vendors must support multiple releases or versions of their software products. Additionally, clients want to leverage their documentation, reusing those documents that apply over different releases for several generations of a product.

* To reduce the resources used for problem resolution, the online representation of the requirements documentation must link to the actual software (at the source code level).

* Information mapping is evolving into a new technical job description. The design of documents for online use includes specifying the font, framing and size for the data. The goal is to make the information more readable and presentable on screen.

* Electronic, or online, viewing of documentation is much less expensive to deliver and easier for clients to use. Experiments with different media, such as CD-ROM, result in even more efficiencies.

A primary use of documentation is the education of the maintenance staff. "A new programmer coming on board needs to know how a program works. So, a first step is producing documentation that ties the design level to the source code," said George Symons, vice president of marketing at ProCase Corp., Santa Clara, Calif.

ProCase's Smartsystem reverse engineers C code into front-end design tools like TeamWork from Cadre Technologies, Inc., located in Providence, R.I., and Software through Pictures from Interactive Development Environments, Inc., San Francisco. Developers can look at both textual and graphical views of the code. They can then incorporate these abstractions into the document they are producing.

When Siemens Infusion Systems wanted to upgrade its level of documentation for FDA review, the firm worked jointly with ProCase to develop an interface to Smartsystem. That interface enabled Siemens to parse its existing C software and feed an internal representation of it into Cadre's TeamWork, according to Koenig.