Documentation Generator

Overview

The software documentation process is an integral part of the software development process. Software documentation is an organized collection of written material which aids developers in understanding software. During the software development process, software development teams generate different kinds of documentation. Some of this documentation is for internal use, some of it is delivered to you (guarantee that the software complies with certain standards,...) The classical approach to documentation generation is to write the documentation in one of the available text-processors, copying certain items (figures, tables, text, ...) from the development tools, and integrating ("pasting") them into the document. A positive side to this approach is the full control over each part of the document. However, it is easy to conclude that with massive projects this task can be an arduous one (for example, if 1000 functions were to be documented in this way). A second flaw to this approach is that each and every change in the project requires the documentation process to be repeated for the altered part. This flaw has a negative effect on how up-to-date the documentation is. The solution lies in connecting the documentation writing tool and the software development tools while at the same time ensuring that the documentation be kept up-to-date automatically.

The solution offered by DA-C is the automation of the software documentation process. The DA-C component which automates this process is the Documentation Generator (DG). As an integral part of DA-C, DG uses all its capabilities to automate the documentation generation process and to ensure high-quality documentation.

Here are the DG goals:

- To automate the software documentation generation process on the basis of various kinds of reports formed by DA-C.
- To achieve the consistency of software and corresponding documentation, that is to produce up-to-date software documentation.
- To achieve facility of use.
- To realize as many present and future DA-C potentials as possible.
- To adapt the form of the reports to your needs and documentation standards.
- To ensure that the same part of the documentation template can be repeated for different objects which are being documented which greatly reduces the time needed to generate documentation for massive projects.

Numerous groups of participants in the software production process will find DG highly useful:

- Coordinators - project-managers for the analysis of work results,
- Software developers and programmers who use DA-C to develop software,
- Sector/company quality control teams,
- Software developers and programmers who use the reverse engineering method to obtain models or document existing systems, and
- Teams in charge of writing user and reference manuals.

Basic Principles

Documentation generation is founded on documentation templates (DTs). A set of documentation templates describes how the software documentation will look when completed. Software documentation is created by the process of generating documentation on the basis of documentation templates.

That is, each documentation template is an RTF document which contains clearly delineated parts - scripts. On the basis of each documentation template, DG generates one or more documents. The generated documents consist of content which also exists in the documentation template, with the difference that instead of script the generated documents contain content generated on the basis of the script.

Documentation generation

Script is written in a macro language specially developed for this purpose, DGML. DGML is a language for "programming" documentation. It encompasses a range of directives meant to ensure full control over the document generation process. DGML also, through predefined functions and data types, allows access to the large number of data contained in the DA-C project. In this way it is possible to:

Display various kinds of reports: Browser reports, VCS reports, graphics reports.

All graphics reports are in WMF (Windows Meta File) format.

Display project data: data on the project itself, data on project objects, and data on messages.

Generating documentation is accompanied by checking the documentation template which results in an error report. Checking the documentation template identifies both syntactic and semantic errors and makes it possible to assess the serviceability and consistency of the generated documentation. Taking into account the potentially long time needed to generate documentation (for a large data set), checking documentation (as the more rapid process) can be performed independently of the documentation generation process.

DG also offers support for creating documentation templates. Creating and updating documentation templates is organized on the basis of cooperation between DA-C and the external text-processor (DTE).

DG ensures interactive and intuitive forming of DGML scripts by means of the Wizard. You begin the operation by choosing a documentation object by activating or selecting it - the documentation object can be any content you want to document. You then access the Wizard. It allows you to document the documentation object by a simple choice of property's. Based on the property's selected, the Wizard create a complete set of DGML scripts and inserts it directly into the active documentation template or onto the Clipboard.

DG supports basic operations for manipulating documentation templates (opening existing ones, creating new templates). DG is also equipped with a range of standard documentation templates created in accordance with documentation templates.

Project Documentation Generator

Overview

Basic Principles

Documentation Template

Editing a Documentation Template

Documentation Generation

Documentation Generator Tutorial

Documentation Generator Message Log

Overview

Basic Principles

Documentation Generator Message Log