How can semi-automatically generated documents be reviewed efficiently?

1. Introduction

Technical documents that have been created semi-automatically are often very extensive. When developing a product according to the V-model the following technical documents are created, among others:

• design specifications,
• analysis documents,
• requirement documents,
• test specifications and test reports.

Document reviews serve to uncover gaps and systematic errors in the documents. This article describes how technical documents can be reviewed in an effective and efficient manner.

2. Effective and efficient review of technical documents

A review can take two forms:

• Walk-through review: The author guides the participants through the document.
• Inspection review: Each participant reads the document independently.

Steps for optimal review preparation

“A successful review depends on selecting the right participants and defining the right review criteria.”

For each chapter or section of the document to be reviewed, determine:

• Who is a responsible person for the content?
• Who is a "project-internal customer", who needs the content?

Sections without "project-internal customers" should be deleted. The review criteria are jointly defined by the review team to ensure that there is a common understanding and that all relevant aspects are covered.

Conducting the review

The review should be conducted as follows:

• Partition the document into review parts,
• Assign each review part to more than one review participant, preferably to all project-internal customers of the review part,
• Once all review participants have provided their review comments, discuss the review comments in a joint session of all review participants and determine the necessary corrections.

As soon as all corrections have been incorporated, the document can be released.

3. Advantages of semi-automatically created documents

Semi-automatically created documents exhibit the following advantages:

• Consistent structure: The document structure is predefined.
• Automatic error detection: Missing or inconsistent entries can be identified automatically.
• No spelling mistakes: Autogenerated texts are standardized.

“Trivial errors such as missing entries or inconsistent links are detected automatically, preferably prior to the review.”

Limits of automation

Certain mistakes can only be detected manually, such as:

• Incorrect assumptions (e.g. maximum incoming disturbances or interferences),
• Suboptimal design decisions (e.g. in the system architecture).

4. Summary

The review of technical documents can be made efficient by:

• involving primarily the “project-internal customers” in the review,
• deleting document parts without “project-internal customers”, and
• the review team defining and accepting on such review criteria that cannot be checked automatically.

The autoConform® software supports the review process by providing automated document checks and by automating traceability. This allows review participants to focus on content errors and minimize the time spent on reviews.