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

TeamWork produced structure charts of the system, which Siemens development staff then modified and put into the documentation this way saved about 12 months of time, said Koenig. "The main benefit was that development resources were not required for the documentation upgrade. Apart from the joint development of the interface, all the work was done through the services of a cooperative student," he added.

Another Smartsystem user is the David Sarnoff Research Center in Princeton, N.J. "We had developed a system of over 40,000 lines of code for a client who was expecting to take over the control of the application," said Walter Paul, a member of the technical staff at the Research Center. To generate the required documentation immediately, the Center chose the Smartsystem running on a workstation from Sun Microsystems, Inc., based in Mountain View, Calif.

Paul said that he found Smartsystem easy to customize. "It takes a long time to create and parse the code repository," he said. Once that is done, however, the tool can seamlessly navigate between diagrams and source code. It also provides debugging features such as in-line code expansion and source code filtering," Paul added.

INTEGRATION IS KEY

Integration of documentation tools usually implies the ability to hook up full-functioned documentation management systems such as those produced by Interleaf and Frame Technology Corp., San Jose, Calif.

Cadre's Ensemble product line, for example, can parse C language programs and produce documentation that feeds Interleaf products. After Ensemble produces the program-level diagrams, structure charts and data dictionary, the user can put them into different sections within Interleaf, and create separate files for different pieces. The user can also annotate the generated documentation and the annotations will not be lost. Attached to each element of the database are status labels--containing name, date and reason for the change--which provide a change control mechanism.

The Space Systems Division of General Dynamics Corp., in San Diego, also works with Interleaf and the front-end tool Software through Pictures from IDE. According to Robert Mattus, a software engineer with the division, they were looking for a way to "do things faster and cheaper" for the space shuttle's National Launch System.

Project engineers used IDE's Software through Pictures to help define the specifications. During the design stage, the engineer creates a mapping (template), which links to the appropriate part of the military standard document (DoD 2167). "The engineer doesn't write documentation; he just annotates various aspects of the software design," said Mattus. "The templates are used to pull out the design information and create the DoD document." IDE's STP can also generate the documentation as of a certain date, thereby providing configuration control.

The developer can then bring the documentation into the Interleaf Publishing System for further polishing before publication. Then the developer can transfer the Interleaf document to the user, under Hypercore on Macintosh. Working with Macintosh icons, the user can access any part of the document. There is no need to know Interleaf.