Parameterizable Documentation Basics

This section is intended to give you a feel for the basic possibilities that are offered by parameterizable documentation. By way of illustration, an extremely simple, and hence rather unrealistic, example is used. The division of the definition process is therefore clearer.

Steps in Document Category Definition

The definition of a document category is largely comparable with producing a paper-based form; it can therefore be broken down into the following stages:

Design Phase

In the first step, the structure of the document category is outlined in abstract terms (“abstract design”). Key question: What are the contents, sequence and layout of the form supposed to be?

Definition Phase

In the second step, the design is developed to establish the specific structure of the document category (“definite design”). Key question: How should the on-screen and printed form (layout) actually appear, at what positions should the fields (elements) appear and what will their designations be?

Generation Phase

Finally, in the third phase, the database structures are generated for storage of the documents, application programs and screens. This step may be compared with printing or photocopying a paper-based form.

The Abstract Design

The general design comprises a number of document elements, each of which may in turn be structured, as well as information as to whether the documentation element is stored in the database, and the positions of the documentation elements relative to each other. The design also indicates the substructures to be created for particular tables. However, it does not contain any of the information necessary for the generation of actual storage structures or processing programs, for example, the names of tables, fields and programs.

Example

The creation of the abstract design is illustrated by the example, admittedly highly simplified, of a"Sonograph Findings".

This graphic is explained in the accompanying text.

Each white rectangle symbolizes a data record in the DE Table; the gray rectangles are the entries to the DE-DE assignment table.

This illustrates that:

The complete document category is described at the top level by a structured documentation element (the "Sonograph Findings" in this example). This is always the case, even when the document category only contains one field, there is this master structure to which the basic documentation element is then assigned.
A structured documentation element may, in turn, contain other structured documentation elements.
Only in the case of unstructured (basic) documentation elements will table fields subsequently have to be created in the database; the "Findings" structure exists enable the use of these structures in other document categories.

In system administration, you can design a completely top down document category. Starting from the document category, with the master element as the top level, you can assign existing documentation elements, or enter and assign new ones. You can also maintain documentation elements and assignments for each individual transport. In this case, the documentation elements must already have been created at the time of assignment.

Definite Document Category Definition

From a newly created document category which, until now only contained a master element, you create a definite document category definition which we call the definite design, by saving.

When you execute the save function, the system will create an entry in the Document Category table and entries in the Documentation Element table. The system will execute a series of presettings, for example, the relative positions of documentation elements are converted from the abstract design into absolute positions on the various screens.

This graphic is explained in the accompanying text.

The gray rectangle represents the document category record (master record); the white rectangles are the documentation elements.

In the master record, apart from descriptive data like name and version number, there is also technical information such as the names of the programs to be generated and the name of the database table in which the document will be stored.

The documentation elements forming part of the document category arise from the replacement of the recursive structures in the abstract document design; this should be indicated in the diagram by partitioning the relevant element records.

Each individual element can be revised manually. In this step you can, for example, change the layout of the fields in the user interface.

Finally, the application programs and table of document data can be generated on the basis of the detailed description.

Background Information on Division into Abstract and Definite Document Category Definition

Separating the "abstract" and "definite" structure definition, and replacing the recursive structure in the specific definition and its redundant storage has a number of advantages:

The recursive structure (in which documentation elements are composed of other documentation elements) is a help during the abstract design stage because it saves the system administrator work when writing definitions. The maintenance of uniformly related structures is simpler as these only have to be defined once and can then be inserted in various document categories.
In the case of the definite definition, it is necessary to process all elements in one list in order, for example, to anchor table and screen field names, as well as to specify screen numbers and absolute display positions relative to the screen. On the basis of the abstract design, default values can be generated for the actual assignments (table field names, screen field names, positions, and so on) which makes the complicated second step considerably easier.
The steps are intuitively structured, and resemble those involved in the design of a paper-based form.
Changes to the general document category definition do not have a direct impact on the definite document category definitions as the latter have been produced by copying. Any changes to the abstract design that have occurred in the meantime are not incorporated until the definite definition is updated.
Less time is required during generation and document processing, as recursive nesting does not have to be reinterpreted.