The documentation standard
shall be prepared to establish the documentation requirements for a specific
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.
Documents are now available in .pdf format: See PDFDOCUMENTS.
Copyright © by Ken Rigby 1995, 1996, 1997, 1998
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
- This standard is to be used primarily for the name
- 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.
- 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.
- 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
- 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
- ISO 9000, AQAP quality systems requirements for
the documentation of systems and software have been taken into account and
should be compatible.
- 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.
List by table the
contents of the document.
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
For a model text see Section 1
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
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
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
- Some of the purposes that documentation and
standardization serve are to:
4.2 General considerations
on document planning and preparation.
- provide managers with
documents to review at significant developmental milestones to determine
that requirements have been met and that resources should continue to be
- record technical information
to allow co-ordination of later development, use, and modification;
- provide authors of documents
and managers of the project development a guide to follow in preparing
and checking documentation;
- provide uniformity of style, format
and content of documentation throughout the project;
- prevention of variety and
promotes variety reduction.
- The manager with responsibility for the specific
discipline program plan shall ensure:
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.
The author of a document should ensure that they
- A documentation plan is
developed early in the process of project development, including:
- Which document types will be
prepared and the appropriate level of detail;
- The dates that documents must
- Document evaluation
procedures, as applicable;
4.2.3 Document audiences.
- An understanding of its
relationship to other associated documentation;
- 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.
- 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.
- An understanding of how to
classify a document. It is the author's duty to allocate the security
- The following shall be considered by authors
when preparing documentation.
- 4.2.4 Document types.
- 4.2.5 Standard Generalized Mark-up Language
- 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
The data prepared in conformance to these requirements will facilitate the
automated storage, retrieval, interchange, and processing of technical
For a model text for Section 4
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
- 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
- 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
- Configuration Management plan;
- Risk Management Plan;
- Data Management Plan
- Documentation Standard;
- Software development plan
- Technical numbering standard;
- Engineering program plan
(Project Management Plan);
- System safety program plan;
- System security program plan;
- Reliability program plan;
- Technical Risk Management
- Maintainability program plan;
- Testability program plan;
- Manufacturing Management Plan;
- Software quality program plan;
- Master record index;
- Version compatibility matrix;
- Physical configuration audit
- Memoranda, letters, minutes,
- and any supporting documents as identified in
the Contract Data Requirements List.
Authors note "insert here a brief description of the above
- System/software engineering documentation.
- System/subsystem specification;
- System/subsystem design documentation;
- CI/PI Development specification;
- Software Requirements Specification;
- Interface Requirements Specification;
- Operational concept document;
- Engineering Drawings;
- Software Design Description;
- Interface Design Description;
- Database Design Description;
- Source code listings;
- Software Product Specification;
- HWCI Product Specification
- 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
- Firmware Support Manual
- Computer Programmer's Manual
- Software User's Manual
- Software Input/Output Manual
list for instructions of preparation.
For a model text for Section 5
(This section contains
information of a general or explanatory nature that may be helpful, but is
For a model text for Section 6
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
number of visitors to this site since the 15th of March 1998
Please send any beneficial comments or
identification of errors using the following form to: firstname.lastname@example.org
Copyright © by Ken Rigby 1995, 1996, 1997, 1998 --
All Rights Reserved