Best Practices - Common to all Documents

Best Practice

Title Page


Best Practice

Here are some important practices to keep in mind when writing the document:


Title Page

The title page must contain the title of the document, the document preparer's name and version number and date of creation or revision of the document. Also contained on the title page, near the bottom, is the copyright notice.

The form of the title is "<ProjectName><TaskName><DocumentType>". The <ProjectName> can be the initials of the project. The <TaskName> can be a subproject name, program name or library name. <DocumentType> must be 'Requirement', 'Specification' or 'Design'. Example: 'ACE Command Parser Requirements'.

The version number of the document usually starts with 0.X during initial development of the document. Each revision of the document that is reviewed by the project developers should have successive minor numbers (example: 0.1, 0.2, 0.3, etc). When the document is complete and ready to be used by other persons on the project the version must be set to 1.0. Each minor revision of the document would increment the minor number (example: 1.1, 1.2, 1.3, etc.). For any major change in the document the major number must be incremented (example: 2.0).

The copyright notice must appear on title page of each document generated. By default the 'All Rights Reserved' copyright notice is used.

1.0 Introduction/Overview

The introduction must contain at least a one sentence statement of the 'mission' or purpose of the project or software component. The remainder of the introduction must describe the purpose of the document and must briefly describe the structure of the document.

There must be enough information in this introduction to allow a person seeing the document for the first time to understand the following:

X.0 Glossary

A list of definitions of terms used in this document.

X.0 Change Log

Each change of this document after the initial release must be described in this section along with the version of the document and the date of the change.

Version

Date

Person

Reason

0.1

Sep 1, 2000

Leon S. Searl

Initial working version.

 


Leon S. Searl

Last Modified: 2001-01-17