Documentation Standard
Section 4 - Model Text

4. GENERAL CONSIDERATIONS

This section discusses the considerations to be addressed when preparing documentation of a project.

4.1 System/software development life cycle.

A system/software development life cycle shall be established as defined in the 'Software Development Standards' document and shall consist of the following phases:

• System requirements analysis and system design;
• Software requirements analysis;
• Preliminary design;
• Detailed design;
• Coding and Unit testing;
• Unit integration and testing;
• CSCI testing
• System integration and testing.

Detailed descriptions of the above phases are provided in the 'Software Development Standards'. Associated with each phase of the software development life cycle a group of documentation shall be prepared; documentation shall be prepared according to Risk Class, Category, and function.

4.2 System/hardware development life cycle.

A system/hardware development life cycle shall be established and comprise the following:

• System/hardware requirements analysis;
• Hardware requirements analysis;
• Preliminary design;
• Detailed design;
• Fabrication;
• HWCI testing;
• System integration and testing.

Detailed descriptions of the above development phases shall be provided in the specific hardware development plan(s). Associated to each phase of the system/hardware development life cycle a group of documents shall be prepared. Model texts (examples) for these documents will be provided in appendixes to this document. No additional document shall be prepared without formal authorization.

4.3 Need for documentation and standardization.

Some of the purposes that documentation and standardization serve are to:

• Provide managers with documents to evaluate a significant developmental milestones to determine that requirements have been met and that resources should continue to be expended;
• Record technical information to allow coordination 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.

4.4 General considerations on documentation planning and preparation.

• 4.4.1 Manager.
• The manager with responsibility for the specific discipline program plan shall ensure:
• A documentation plan should be 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 the documents must be available;
  3. Document evaluation procedures, as applicable.
• The prepared documents are updated properly and in a timely manner.

NOTE: the documentation program plan shall be included in the specific speciality discipline plan, for example, SDP, HDP, SEMP, etc.

4.4.2 Authors.

The author of a document should ensure that they have:

• 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 in a document that is intended to be very general is written before a later section that is intended to provide specifics. This often leads 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 started;
• 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, a group of individuals, user groups, and development groups.

4.4.3 Document audiences.

The following shall be considered by authors when preparing documentation. When each document is written the function of the audience that will use the document must be considered to ensure that the information is presented using appropriate terminology and to an adequate level of detail.

• Audience types;
  Each document type is prepared for and read by a specific audience. The audience may be an individual or group of individuals. The two audiences involved in all projects will be the development Group (Team) and User groups.
  
  1. The development group may be the acquirer or a supplier. As a minimum, the group shall perform the design and coding functions;
  2. The User Group is usually the acquirer or is agent that requested the project. As a minimum, the User Group comprises of those who provide inputs and those who utilize the outputs from the project.
• Audience composition;
  Regardless of the organizational relationships between the development team and the user group, the functions of the two are separate. Both of these groups may consist of personnel with separate titles and functions that include the following:

4.4.4 Document types.

Document types are produced during the evolutionary development of the system and its comprising hardware and software.

4.4.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 parameters.
This data shall be prepared in conformance to these requirements and will facilitate the automated storage, retrieval, interchange, and processing of technical documents.

Under construction.

Back to Home page MANAGING STANDARDS Home page

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