Documentation Standard
Section 3.1 - Model Text

3.1.3 Language style.

The paramount consideration in a specification and its associated documentation is its technical essence, and this should be presented in language free of vague and ambiguous terms using the simplest words and phrases that will convey the intended meaning. Inclusion of essential information shall be complete, whether by reference or statements to other documents. Consistency in terminology and organization of material will contribute to the documentation's clarity and usefulness.
Punctuation should aid reading and prevent misreading. Well-planned word order requires a minimum of punctuation. When extensive punctuation appears necessary for clarity, consideration should be given to revising the sentence, since misplaced or omitted punctuation marks can sometimes change the meaning of the sentence completely. To avoid this possibility, consideration should be given to converting clauses of a compound sentence to separate sentences. Long sentences need to be broken down into shorter ones. If the resulting separate sentences need to remain linked to each other they should be separated by a semi-colon, but not by a comma. All sentences shall be complete and in accordance with the rules of grammar. As a general rule, sentences should be limited to a maximum of 28 words.
Documentation should be clear, unambiguous and easy to read. Wording shall be plain and clear with concise terminology and vocabulary.

3.1.3.1 Capitalisation, spelling, punctuation, etc.

The guide for capitalization, spelling, punctuation, syllabification, etc., shall in the U.K. be the 'Concise Oxford Dictionary' and in the US 'Merriam/Websters international dictionary' may be used. Avoid pronouns where possible. Repeat the noun to avoid any misinterpretation.

In addition the following rules shall be observed:

• Use of an analogy or a metaphor should be avoided, if possible. If metaphors are used, they shall be used consistently.
• Split infinitives shall be avoided as they can make the text confusing or difficult to understand.
• Parentheses shall not be used to enclose essential information because they might reduce the importance of that information. Information that is purely commentary, however, should be in parentheses or in a footnote in a different typeface.
• Sentences should not attempt to cover both the singular and plural options in a single construction using brackets to enclose the alternatives. For example, instead of "... the selected file(s) is (are) saved.", the following could be used. "All the files that have been selected have been saved."
• Quotation-marks should be used to enclose quotations and the referenced document titles. Quotation-marks may be single (') or double (") however, the use of quotation-marks shall be consistent throughout the document. In particular, quotation-marks shall not be used to enclose any text that the user has to type. If it is necessary to highlight text that users have to type, a different typeface or font should be used.
• Square brackets or braces should not be used in text, although they may be necessary in mathematical or syntactic information, in which case they shall be used strictly according to the rules of the relevant discipline.
• Use of capital letters shall observe the following rules:
  1. Capital letters shall be kept to a minimum;
  2. In the names of products and companies, capital letters shall be used precisely as in the registered product and company names;
  3. For titles of documents, headings, and titles of figures and tables, shall be consistent;
  4. In the titles or headings of tables, figures, and lists, the initial word shall begin with a capital letter.

3.1.3.2 Definitions and terminology.

Definitions and terminology shall be in accordance with the identified dictionary unless it is defined in the glossary Terminology should be consistent throughout the documentation. When referring to a particular item, use the same phrase or word, particularly when referring to technical terms and items.

3.1.3.3 Abbreviations and acronyms.

The first time an abbreviation or an acronym is used in text, it shall be placed in parentheses following the word or term spelled out in full; e.g., MegaHertz (MHz), Software Development Plan (SDP). This rule does not apply to abbreviations or acronyms used for the first time in tables and equations; uncommon abbreviations so used shall be explained in the text or footnotes.
A total list of all abbreviations and acronyms used throughout the document and not defined in the 'Concise Oxford Dictionary' shall be listed with their meaning in a paragraph contained within the section (normally section 6) identified as NOTES.
Only abbreviations authorized for use in specifications, standards, and other technical documents shall be used. Lists of commonly used symbols and abbreviations are contained various organizational documents. Reference the applicable standards from which the symbols and abbreviations are taken must be referenced within the document.

For more details acronyms and abbreviations see Paragraph 3.1.3.3

3.1.3.4 Symbols.

Symbols shall not be used in text, but may be used in equations and tables. Graphic symbols, when used in figures shall be in accordance with ISO standards (Any symbol formed by a single character should be avoided if practicable, since an error destroys the intended meaning).
The only symbols normally used in text are"+", "-", "+/-, to express ranges or tolerances, the degree symbol "o", and metric symbols, such as "mm" and "mg". Other symbols shall not be used in text, but may be used in equations and tables were allowed by the adopted standard.
Graphic symbols, when used in figures shall be in accordance with recognized standards.
NOTE: A total list of all abbreviations and acronyms used throughout the document being prepared that has not been defined in the identified dictionary or MIL-STD-12 shall be listed with their meaning in a paragraph contained within the section identified as NOTES.

3.1.3.5 Proprietary names.

Trade names, copyrighted names, or other proprietary names applying exclusively to the product of one company shall not be used unless the configuration item(s) require source control or cannot be adequately described because of the technicality involved, construction, or composition. In such instances, one, and if all pertinent requirements are specified, several, commercial products may be included by inserting the word "or equal" after the trade name to assure wider competition and that bidding will not be limited to a particular make specified.
The same applies to manufacturer's part numbers or drawing numbers for minor parts when it is impractical to specify all detail requirements in the document. In all instances where "or equal" is permitted, the particular characteristics required shall be included to define "or equal".

3.1.3.6 Commonly used words and phrasing.

Certain words and phrases are commonly used in specifications and their associated documents. The following rules shall be followed:

• Referenced documents shall be cited thus:
  1. "conforming to ....."
  2. "as specified in ...."
  3. "in accordance with ...."
• "Unless otherwise specified" shall be used to indicate an alternative course of action. The phrase shall always come at the beginning of the sentence, and if possible, at the beginning of the paragraph. This phrase shall be used only when it is possible to clarify its meaning by providing a reference such as to Section 6 of the document for further clarification in the contract or order or otherwise.
• When making reference to a requirement in the document and the requirement referenced is rather obvious or not difficult to locate, the simple phrase "as specified herein" is sufficient and should be used.
• The phrase "... to determine compliance with ..." or "... to determine conformance to ..." should be used in place of "... to determine compliance to ...". In any case use the same wording throughout.
• In stating positive limitations, the phrase shall be stated thus: "The diameter shall be no greater than ...".
• The emphatic form of the verb shall be used throughout the specification; i.e., state in the requirements section that "The indicator shall be designated to indicate ...", and in the section containing test provisions "The indicator shall be turned to zero and 230 volts alternating current applied." For specific test procedures, the imperative form may be used provided the entire method is preceded by "the following tests shall be performed," or related wording. Thus, "Turn the indicator to zero and apply 230 volts alternating current."
• Capitalise the words "drawing," "bulletin," etc., only when they are used immediately preceding the number (identifier) of a document. However, Government and military standards (DEF STANs, MILs, JSPs, etc.,), and handbooks shall be identified in text only by their symbol and identifier; thus "MIL-STD-000, not, "specification MIL-STD-000."
• Use the following prepositional phrases when referencing figure or table information: "on a figure" and " in a table".
• Wherever possible, words that have been made up shall be avoided, because they have no precise defined meaning, and different users may interpret them in different ways. Made-up words that are in common use on the specific project may be used in documents, but they must be clearly defined in each document, to ensure that there is no possibility of misunderstanding.

3.1.3.7 Generic use of the word system.

The word 'system' may be used generically in the documentation to be synonymous with the words system, subsystem, prime-item, or segment, as applicable

3.1.3.8 Use of "shall", "will", "should", and "may".

Use "shall" whenever a document expresses a provision that is binding. Use "should" and "may" wherever it is necessary to express non-mandatory provisions. "Will" may be used to express a declaration of purpose on the part of the user. It may be necessary to use "will" in cases where the simple future tense is required, that is, power for the motor will be supplied by the ship. "Must" shall be used for legislative or regulatory provisions.

Derogation from requirements in specifications (indicated by the words "shall" or "must") is not open to the designer without formal agreement (deviation/waiver or Change request) in writing from the project manager or director.

3.1.3.9 Forms and proformas.

Some of the information specified in individual paragraphs of the document types may be presented on approved forms or proformas. The establishment of specific forms to be used for project use shall be defined in this document. However, because of the dependency of some forms on particular computer software, hardware, and management practices at the individual companies precludes precise definition.
 
Although the use of forms in encouraged, the information contents of the document types must still be followed. If a form is used as a figure or as an appendix, it shall be referenced from an appropriately numbered paragraph within the main body of the document. 

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