This paragraph includes the requirements for style, format, and general instructions for preparing and evaluating documentation. This includes material arrangement, titling, paragraphing, numbering, heading, security, binding, checks and concluding material.
Documentation shall normally contain six numbered sections, and appendices as required, titled and numbered as follows:
or, as specifically defined in the model text appended to this document.
Subject matter shall be kept within the scope of the section so that the same kind of requirements or information will always appear in the same section of every document. Except for appendices, if there is no information pertinent to a section, the following shall appear below the section heading:
"This section is not applicable to this document."
Each section shall be divided into numbered and titled paragraphs and subparagraphs as necessary. The notation "Not applicable" shall be entered after each paragraph number and title that is not applicable. Subordinate paragraph headings may be added under the most suitable major paragraph heading in the outline prescribed in the model text to enhance readability. These subparagraphs shall be numbered sequentially. Paragraphs and subparagraphs shall be progressively indented for each new level. The amount of indentation should be increased by the same amount for each new level (3 to 5 is recommended).
In the event that a paragraph or subparagraph has been tailored out, a statement to that effect shall be added directly following the heading of each such (sub)paragraph. If a paragraph and all of its subparagraphs are tailored out, only the highest level paragraph heading need be included.
#For sample text see Paragraph 3.1.3
Each paragraph and subparagraph shall be numbered consecutively within each section of the document, using a full stop (.) - period- to separate the number representing each breakdown. Each section, paragraph and subparagraph shall be numbered consecutively using a decimal notation as follows:
Itemization (lists) within a paragraph or subparagraph shall be identified by lower-case letters followed by a full stop to avoid confusion with paragraph numbers.
Portions of paragraphs shall not be underlined and word or phrases shall not be capitalized for the sake of emphasis with the exceptions noted in 3.1.4.1. All of the requirements are important in obtaining the desired product or service. Preamble and acquisition notes shall not be underlined. Table and figure titles may be underlined.
Cross-references, that is references to parts within the document, shall be held to a minimum. Cross-reference shall be used only to clarify the relationship of requirements within documentation and to avoid inconsistencies and unnecessary repetition. When cross-reference is to a paragraph or subparagraph within the document, the cross reference shall be only to the specific paragraph number. The word paragraph shall not appear, for example, "(see 3.1.1)".
Each page prior to Section 1 shall be numbered in lower case roman numerals beginning with page ii, numbering of page (i) is optional. Each page starting from Section 1 to the appendixes shall be consecutively numbered in Arabic numerals. If the document is divided into volumes, each such volume shall restart the page numbering sequence.
The title "CONTENTS" in capital letters shall head the table of contents page(s). Identification numbers and headings for sections and paragraphs shall be shown in the listing and may be shown for subparagraphs. The context also shall include figures, tables, appendices, and index in that order if they are included. Page numbers shall be entered corresponding to each section or paragraph title.
The method of specifying dates on documents shall be by day-month-year for entry at the right-hand side of the footer on each page. The date shall also be entered directly beneath the document identifier on the title page.
For hardcopy formats, the documentation may be printed on one or both sides of each page (single-sided or double-sided. All printed pages shall contain a document control number and the date of the document. The document control number should be centered at the top of each page. Document control numbers shall include revision and volume identification as applicable.
A figure is a picture or graphic (illustration) and constitutes an integral part of the document. It shall be clearly related to, and consistent with, the text of the associated paragraph. Figures should not be confused with numbered and dated drawings referenced in the text which shall be listed in section 2 and not physically incorporated in the document.
For more details see Paragraph 3.1.11
A table is an arrangement of data in lines and columns. A table shall be used when information can be presented more clearly than as text. Elaborate or complicated tables shall be avoided. References in text shall be sufficiently detailed to make the purpose of the table clear. The table shall be restricted to data pertinent to the associated text. All table columns should have an explanatory heading, and, where appropriate, units of measurement. Tables should not duplicate results presented elsewhere in the document, for example, graphs.
For more details see Paragraph 3.1.12
Presentation conventions for lists, shall be as follows:
The two types of list styles shall not be mixed within a single list.
Fold outs shall be avoided except where required
for legibility. Large tables or figures may be broken out so that
they may be printed on facing pages. Where foldouts are required,
they may be printed on facing pages. Where foldouts are required,
they should be grouped in one place, preferably at the end of
the document (in the same location as figures) and suitable reference
to their location shall be included in the text.
Charts, graphs, or other information which cannot be contained
on pages of the specified size (A4) shall be arranged and folded
so as to fit properly within the covers. Whenever possible, lengthy
tables shall be reformatted as multiple, single page tables. Where
foldouts cannot be avoided, they should be grouped in one place,
preferably at the end of the document (in the same location as
the figures) and suitable reference to their location shall be
included in the text.
A document shall not include contractual requirements which are properly a part of the contract, such as cost, quantity required, time or place of delivery, methods of payment, liquidated damages, rework, repair, resubmittal, requirements for preparation, submission, delivery, approval, and distribution of data, record keeping, and actions to be taken by the purchaser for accepting non-conforming material. Contractual, administrative, and warranty provisions of contracts, shall not be made part of the requirements in the document. Contractual and administrative provisions considered essential for acquisition may be included in section 6 (NOTES) of the document for information. When this is done, a parenthetical reference to the applicable paragraph in section 6 shall follow the terms to indicate the existence of a definition, for example, "(see 6._._)". Where standard definitions exist in purchaser documents, the definition should be quoted word for word with a reference to the source.
The inclusion of a definition can be avoided if requirements are properly stated. When the meaning of one or more terms must be established, definitions shall be placed in the text. However, it is often clearer to list one or more definitions in section 6, especially where the terms are used in many places throughout the document. Definitions shall be listed in alphabetical order in section 6. When this is done, a parenthetical reference to the applicable paragraph in section 6 shall follow the terms to indicate the existence of a definition, for example, "(see 6._._)". Where standard definitions exist in Government documents, the definition should be quoted word for word with a reference to the source.
For more details see Paragraph 3.1.18
Referenced documents shall be listed by document
identifier and titles in section 2 of the document, and may 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.
All and only those documents referenced in section 3, 4, 5 and
appendixes of the document shall be listed in section 2 of the
document. If numerous, section 2 may reference an appendix or
other appropriate document containing a complete listing. References
shall be confined to documents currently available at the time
of issue of current revision of the document and have been thoroughly
reviewed and considered suitable for use in software development.
Figures bound integrally with the document shall not be listed
in section 2.
For more details see Paragraph 3.1.20
For more details see Paragraph 3.1.21
Documents and data items shall be identified by a common scheme defined in Technical Numbering Standard.
When required, one or more Appendixes and an index shall be included as an integral part of a document.
For more details see Paragraph 3.1.22
Large documents may be divided into Volumes where
practicable. Each volume shall be identified directly below or
after the document identifier in the form "Volume x of y",
where x and y are Arabic numerals. The total number of volumes
shall be identified by y. Individual volumes shall be identified
as x (in the range 1 to y). Each volume shall restart the page
numbering sequence.
Volume 1 of a document shall specify the general requirements
common to all of the document. Additional volumes will specify
the requirements for specific areas identified by Volume 1. The
total number of pages comprising each volume shall be identified
on page (i).
The total number of pages comprising the document that is, inclusive of the title, table of contents, appendixes, and annexes pages shall be identified with their security classifications (if applicable) on the title page (i).
Normally section 6 of a document will contain notes.
Notes are information which are explanatory and non-mandatory
in nature.
For more details see Paragraph 3.1.25
As English commentary cannot be checked to the same extent as formal specifications. Nevertheless, many typographical and some more serious errors can be avoided by carrying out the following checks which although weak in themselves, give a reasonable degree of assurance when used in combination.
Documentation shall be typewritten or copies of typewritten material, print fonts used should conform to the following:
Preparers of documentation are requested to conform
or use a near equivalent of these fonts in the interests of standardization.
Documents shall be type written using non-exotic (e.g., Gothic)
typeface.
Documents shall be legible to the extent they can be easily read.
Type smaller than standard pica (10 point) is not considered legible.
Documents shall be of a reproducible quality.
Documentation shall be bound by means suitable for
holding the document together and for the removal and insertion
of change or revision pages without the use of special tools.
Staples, spiral-wire, glue, or multi-loop plastic bindings, or
similar devices are not acceptable.
Front and back covers shall be of card stack or other similar
material which will protect the document and provide adequate
support when stored on library shelving.
When documents are bound, they shall be bound individually; documents
shall not be bound together, for example, in the same ring binder.
Each document prepared shall contain an authorization
sheet (normally page ii) which will provide the name(s) of the
author(s), his immediate supervisor (technical authority), and
the document's technical or project authorizer whichever is applicable.
The author(s) shall sign the "Prepared by" space when
the document is completed in draft form. His immediate supervisor
or technical authority shall sign the "Approved by"
(to ensure technical correctness) space prior to distribution
for internal review. The "Authorized by" space shall
be signed by the appointed head of the specific project Authority
responsible for the preparation of the document after or during
a management review.
Documentation identified on the Data Requirements List (CDRL)
of the System Specification' or 'Statement of Work' shall have
the authorization sheet replaced by the acquirers official form
and completed in accordance with the data management procedures.
The total number of pages shall be identified on the title page
as follows: 'This document contains (total number of pages)
pages.'
The margin nearest the binding edge shall be at least 2.5cm (1 inch) in width. Page margins at the top, foot and the opposite side to the binding edge shall be at least 1.25 cm (0.5 inch) in width. Paragraphs may be indented with up to 5 spaces to at least the fourth level and the text justified to the left margin.
A foreword shall be prepared for standards and handbooks and shall include an implementation paragraph and a beneficial comments paragraph. If desirable, additional numbered statements may be included to explain the reasons or purpose for a new document or give background information in the case of a revised document. The foreword may also include a brief resume of development history and a statement of reason for a particular format or sequence in the presentation of specific requirements. The foreword shall appear in the printed text beginning on the back side of the self cover, and shall be numbered at the lower center of each page, beginning with the Roman numeral ii.
A distribution statement will be required on all technical data. Distribution statements shall be used to mark technical data to denote the extent of its availability for distribution. The distribution statements shall be distinct from the security classification markings, and shall be used on classified and unclassified data to restrict dissemination beyond the limits provided by applying security clearance and need-to-know controls and to control dissemination of data following declassification.
To be amplified.
The method of presenting cautions, notices, and warnings
shall be explained at the beginning of a document that uses them.
The headings shall be presented in a consistent form wherever
they appear. The headings "CAUTION", "NOTICE",
and "WARNING" shall be given emphasis, for example,
by using bold, upper-case or large type or in combination.
The margin nearest the binding edge at the top shall be at least 25 mm (1 inch) in width. Page margins at the top, bottom and the opposite side to the binding edge shall be at least 12.5mm (0.5 inch) in width. Paragraphs may be indented with up to 3 spaces to at least the fourth level with the text justified to the left margin. Text within each paragraph should not be indented. Headers and footers may contain the security marking and shall be located centrally within the top and bottom page margins. Page numbers shall be positioned centrally in the row immediately prior to the bottom page margin.
Manuscripts shall be prepared for reproduction. If
composition (typesetting) is required, the approved standardization
document manuscript shall be typed either single or double spaced.
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
Originated 7th June 1995.