Documentation Standard
- Model Text

The documentation standard shall be prepared to establish the documentation requirements for a specific project.
This page and its allegiance pages may be copied in their entirety with the copyright kept intact. However, all rights are reserved by the author.
See Technical Managment - documentation standard for more up-to-date information.

Ken Rigby
ADDRESS kenr@wysywig.airtime.co.uk

Title page

• Foreword
• Contents
• Body
  • 1. SCOPE
  • 2. REFERENCED DOCUMENTS
  • 3. REQUIREMENTS
  • 4. GENERAL CONSIDERATIONS
  • 5. DOCUMENTS TO BE PREPARED
  • 6. NOTES
  • APPENDIXES

Title page

Title pages shall contain a front cover, authorization page, review and history, foreword, and a table of contents, figures, tables, appendixes in that order. For a model text see  Documentation Title page

Foreword

1. This standard is to be used primarily for the name of project.
2. Any beneficial comments (recommendations, additions, deletions) and any pertinent data which may be of use in improving this document should be addressed to: name of organization.
3. This standard consists of general and detailed requirements (codes of practice, work instructions, etc.,) for the preparation, assessment, change, revision, to ensure the inclusion if essential requirements, and to aid in the analysis of systems, hardware and software documentation. Detailed work instructions and codes of practice will be included in the model texts to provide an effective integrated approach to the design, development and maintenance of the systems and comprising HWCIs and CSCIs.
4. Appendixes will provide an example of the format and content of the specific document required for the preparation during the definition of the system, and the hardware and software development phases.
5. The intention of this document is to provide users, managers, systems/software engineers, programmers, scientists, etc., with technical/work instructions, codes of practice, information and regulations as required by the recognized national and international standards.
6. ISO 9000, AQAP quality systems requirements for the documentation of systems and software have been taken into account and should be compatible.
7. If documents are required to be marked-up (tagged) it shall be in accordance with ISO 8879 (SGML).
   SGML shall be used:
   • to describe the logical structure of technical publications in unambiguous grammar;
   • to assure automated quality control over adherence to that structure, and;
   • to deliver and store technical publication text in the most easily maintained and updated form.

Contents

List by table the contents of the document. 

1. SCOPE

The 'Scope' section is primarily intended to identify for its users or potential users, the extent and limitations of the subject matter covered by the document. It shall consist of a clear concise description of the subject covered and, if applicable any restrictions or exclusions. It may contain whenever necessary, information as to the use of items.
In the case of items having a range of possible uses or applications, the particular uses intended shall be specified. If appropriate, data on the main units and sub-units forming part of the item and/or the system in which the item itself is used shall be provided. The content shall be sufficiently complete and comprehensive to describe in a broad way the item covered in terms that may be interpreted by suppliers familiar with applicable terminology and trade practices.
For a model text see  Section 1

2. REFERENCED DOCUMENTS

Referenced documentation shall be listed by document number (identifier) and titles in section 2, and shall include specific issue or revision where necessary to rigidly control the configuration or implementation of the configuration item, material or process. The title of each document shall be that appearing on the document itself rather than that shown in an index.
For a model text for Section 2

3. REQUIREMENTS

General requirements for types, forms, and language style for the specifications and associated documentation shall be in accordance with MIL-STD-970/490, DEF STAN 05-28, and JSP 188. When no specific layout format has been identified a logical structure will be adopted.
All documentation prepared in accordance with the 'Documentation Standard' shall be reviewed during and on completion of a phase or stage of development.
The concept of minimum documentation shall be evident. All stipulated plans, reports, and other data items shall be used to record engineering outputs. The use of commercial or other existing documentation, may be substituted for all or part of a document if they contain the required data. However, written approval must be gained from the relevant SEMG and QA authorities and documented in the relevant plan. For a model text for Section 3

4. GENERAL CONSIDERATIONS

As defined in the Systems Engineering Management Plan the system life cycle consists of four phases:

• Concept exploration;
• Demonstration and validation;
• Engineering and manufacturing development;
• Production and deployment.

In each phase a set of documentation shall be prepared.

• 4.1 Need for documentation and standardization.
• Some of the purposes that documentation and standardization serve are to:
  1. provide managers with documents to review at significant developmental milestones to determine that requirements have been met and that resources should continue to be expended;
  2. record technical information to allow co-ordination of later development, use, and modification;
  3. provide authors of documents and managers of the project development a guide to follow in preparing and checking documentation;
  4. provide uniformity of style, format and content of documentation throughout the project;
  5. prevention of variety and promotes variety reduction.
• 4.2 General considerations on document planning and preparation.

• 4.2.1 Manager.

• The manager with responsibility for the specific discipline program plan shall ensure:
  1. A documentation plan is developed early in the process of project development, including:
     1. Which document types will be prepared and the appropriate level of detail;
     2. The dates that documents must be available;
     3. Document evaluation procedures, as applicable;
• The prepared documents are updated properly and in a timely manner. Note: the documentation plan shall be included in the specific speciality discipline plan, for example, SDP, HDP, SEMP, etc.
• 4.2.2 Authors.
• The author of a document should ensure that they have:
  1. An understanding of its relationship to other associated documentation;
  2. An understanding of the overall content required in the document that is to be prepared. Frequently, a section within a document that is intended to be very general is written before a later section that is intended to provide specifics. This can often lead to the inclusion of too much detail in the general section. This can be avoided by reviewing the outline of the document type before writing has begun.
  3. An understanding of the audience who will use the document. For example, although "input" is discussed in the operation and support documents the detail presented in each is different since each is intended to be used by a different audience. Audience types, are, individuals, groups of individuals, user groups, and development teams.
  4. An understanding of how to classify a document. It is the author's duty to allocate the security classification.
• 4.2.3 Document audiences.

• The following shall be considered by authors when preparing documentation.
• 4.2.4 Document types.
• 4.2.5 Standard Generalized Mark-up Language (SGML).
• When documentation is required to be marked-up (tagged) it shall be as a minimum to ISO 8879 (SGML). ISO 8879 defines a basic set of requirements for the digital data form of page-oriented technical publications.
  The data prepared in conformance to these requirements will facilitate the automated storage, retrieval, interchange, and processing of technical documents.

For a model text for Section 4

5. DOCUMENTS TO BE PREPARED

This section identifies and describes briefly the purpose and content of the individual documentation to be prepared during the total system life cycle.
The documentation set shall fulfil the requirements required by MIL-STD-961/970/490, JSP 188, ISO 9000, etc. This section can be divided into the following categories:

• Project Standards (Management data items)
• System/software engineering sys/sw design data items
• Hardware engineering H/W design data items
• Software Test S/W Test data items
• Hardware Test H/W Test data items
• Operational and support Op and support data items

• 5.1 Project 'standards' documentation.
• A tentative list of proposed documentation is provided by list of proposed documentation.
  Project documentation (referred to as project "standards" or "quality plan") are regarded as management data items and shall be used to manage the development and production of systems, subsystems, and its comprising hardware, and software during the system life cycle as defined the contractual standard:
  The following documents, if applicable, are in this category:
  • Project (Program) Plan;
  • Systems engineering management plan;
  • Configuration Management plan;
  • Risk Management Plan;
  • Data Management Plan
  • Documentation Standard;
  • Software development plan (overall)
  • Technical numbering standard;
  • Engineering program plan (Project Management Plan);
  • System safety program plan;
  • System security program plan;
  • Reliability program plan;
  • Technical Risk Management Plan;
  • Maintainability program plan;
  • Testability program plan;
  • Manufacturing Management Plan;
  • Software quality program plan;
  • Master record index;
  • Version compatibility matrix;
  • Physical configuration audit plan;
  • Memoranda, letters, minutes, reports, etc.
• and any supporting documents as identified in the Contract Data Requirements List.
  Authors note "insert here a brief description of the above docs".
• System/software engineering documentation.

1. System/subsystem specification;
2. System/subsystem design documentation;
3. CI/PI Development specification;
4. Software Requirements Specification;
5. Interface Requirements Specification;
6. Operational concept document;
7. Engineering Drawings;
8. Software Design Description;
9. Interface Design Description;
10. Database Design Description;
11. Source code listings;
12. Software Product Specification;
13. HWCI Product Specification

• Test Documentation

• System/subsystem Test Plan
• Software Test Plan
• Test Requirements Document
• Software Test Description (/CSCI)
• Software Test Report (/CSCI)
• Acceptance Test Procedure
• Acceptance Test Report

• Operation and Support Documentation

• Firmware Support Manual
• Computer Programmer's Manual
• Software User's Manual
• Software Input/Output Manual

• Under construction.

See DID list for instructions of preparation.

For a model text for Section 5

6. NOTES

(This section contains information of a general or explanatory nature that may be helpful, but is non-mandatory.)

For a model text for Section 6

APPENDIXES

For a model text for Appendixes

Back to top of page Click here
For Home page MANAGING STANDARDS Home page

Originated on the 31st of May 1995

The total number of visitors to this site since the 15^th of March 1998
LE FastCounter

Please send any beneficial comments or identification of errors using the following form to: mailto:%20kenr@wysywig.airtime.co.uk