**Table of contents**

[15 User documentation 15-1](#__RefHeading___Toc23641996)

[15.1 General 15-1](#general)

[15.1.1 Matching documentation to users
15-2](#matching-documentation-to-users)

[15.1.2 Making documentation appear easy to use
15-3](#making-documentation-appear-easy-to-use)

[15.2 Writing user documentation 15-4](#writing-user-documentation)

[15.2.1 Organization 15-4](#organization)

[15.2.1.1 Titles and headings 15-4](#titles-and-headings)

[15.2.1.2 Numbering of sections and subsections
15-5](#numbering-of-sections-and-subsections)

[15.2.1.3 Advance organizers 15-6](#advance-organizers)

[15.2.1.4 Internal cross references 15-7](#internal-cross-references)

[15.2.1.5 Task versus list orientation
15-7](#task-versus-list-orientation)

[15.2.2 Paragraphs 15-7](#paragraphs)

[15.2.3 Sentences 15-8](#sentences)

[15.2.3.1 Choice of wording 15-8](#choice-of-wording)

[15.2.3.2 Writing level, readability 15-8](#writing-level-readability)

[15.2.3.3 Length 15-9](#length)

[15.2.3.4 Complexity 15-9](#complexity)

[15.2.3.5 Word order 15-9](#word-order)

[15.2.3.6 Voice 15-10](#voice)

[15.2.3.7 Person and mood 15-10](#person-and-mood)

[15.2.3.8 Positive, not negative wording
15-10](#positive-not-negative-wording)

[15.2.3.9 Standard phrases 15-11](#standard-phrases)

[15.2.3.10 Capitalization, punctuation, and hyphenation
15-11](#capitalization-and-punctuation)

[15.2.4 Words and symbols 15-12](#words-and-symbols)

[15.2.4.1 Consistency 15-12](#consistency)

[15.2.4.2 Short, high-frequency words
15-12](#short-high-frequency-words)

[15.2.4.3 Concrete, non-ambiguous words
15-13](#concrete-non-ambiguous-words)

[15.2.4.4 Standard words 15-13](#standard-words)

[15.2.4.5 Pronouns 15-14](#pronouns)

[15.2.4.6 Definitions 15-14](#definitions)

[15.2.4.7 Abbreviations and acronyms 15-14](#abbreviations-and-acronyms)

[15.2.4.8 Spelling 15-16](#spelling)

[15.2.4.9 Numbers 15-16](#numbers)

[15.2.4.10 Units of measurement 15-17](#units-of-measurement)

[15.2.4.11 Letter symbols and mathematical signs
15-17](#letter-symbols-and-mathematical-signs)

[15.2.4.12 Graphic symbols 15-17](#graphic-symbols)

[15.2.4.13 Other symbols 15-18](#other-symbols)

[15.3 Layout and formatting 15-18](#layout-and-formatting)

[15.3.1 Document-level considerations
15-18](#document-level-considerations)

[15.3.1.1 Size 15-18](#size)

[15.3.1.2 Binding 15-19](#binding)

[15.3.2 Page-level considerations 15-19](#page-level-considerations)

[15.3.2.1 Margins 15-19](#margins)

[15.3.2.2 Headers and footers 15-20](#headers-and-footers)

[15.3.2.3 White space 15-21](#white-space)

[15.3.2.4 Right-and left-hand pages 15-22](#right-and-left-hand-pages)

[15.3.2.5 Page numbering 15-23](#page-numbering)

[15.3.2.6 Columns 15-24](#columns)

[15.3.2.7 Foldout pages 15-24](#foldout-pages)

[15.3.3 Typographic issues 15-25](#typographic-issues)

[15.3.3.1 Type size 15-25](#type-size)

[15.3.3.2 Line length 15-26](#line-length)

[15.3.3.3 Line spacing 15-26](#line-spacing)

[15.3.3.4 Justification 15-27](#justification)

[15.3.3.5 Type style (font) 15-28](#type-style-font)

[15.3.3.6 Upper versus mixed case text
15-28](#upper-versus-mixed-case-text)

[15.3.3.7 Typographic emphasis 15-29](#typographic-emphasis)

[15.3.3.8 Print contrast, quality 15-30](#print-contrast-quality)

[15.3.3.9 Color and shading 15-31](#color-and-shading)

[15.4 Components of documents 15-31](#components-of-documents)

[15.4.1 Cover page 15-34](#cover-page)

[15.4.2 Table of contents 15-34](#__RefHeading___Toc23642057)

[15.4.3 Lists of exhibits 15-35](#lists-of-exhibits)

[15.4.4 Figures 15-36](#figures)

[15.4.4.1 General 15-36](#general-1)

[15.4.4.2 Identification 15-36](#identification)

[15.4.4.3 Location 15-36](#location)

[15.4.4.4 Style 15-37](#style)

[15.4.4.5 Content 15-38](#content)

[15.4.4.6 Orientation 15-38](#orientation)

[15.4.4.7 Oversize figures 15-38](#oversize-figures)

[15.4.5 Tables 15-39](#tables)

[15.4.5.1 General 15-39](#general-2)

[15.4.5.2 Identification 15-39](#identification-1)

[15.4.5.3 Location 15-40](#location-1)

[15.4.5.4 Formatting 15-40](#formatting)

[15.4.5.5 Content 15-40](#content-1)

[15.4.5.6 Orientation 15-41](#orientation-1)

[15.4.5.7 Oversize tables 15-41](#oversize-tables)

[15.4.6 Lists 15-41](#lists)

[15.4.7 Formulas and equations 15-42](#formulas-and-equations)

[15.4.8 Warnings, cautions, and notes
15-43](#warnings-cautions-and-notes)

[15.4.9 Appendixes 15-44](#appendixes)

[15.4.10 Glossary 15-45](#glossary)

[15.4.11 Index 15-45](#index)

[15.4.12 User feedback forms 15-46](#user-feedback-forms)

[15.4.13 Tabs 15-49](#tabs)

[15.4.14 Footnotes 15-49](#footnotes)

[15.4.15 Copyright and patent issues
15-50](#copyright-and-patent-issues)

[15.4.16 Publication date 15-50](#publication-date)

[15.5 Specific user document contents
15-50](#specific-user-document-contents)

[15.5.1 Proceduralized instructions 15-50](#proceduralized-instructions)

[15.5.1.1 General 15-51](#general-3)

[15.5.1.2 Organization and content 15-51](#organization-and-content)

[15.5.1.3 Format 15-53](#format)

[15.5.1.4 Wording of steps 15-53](#wording-of-steps)

[15.5.1.5 Branching and cross-references
15-55](#branching-and-cross-references)

[15.5.1.6 Miscellaneous 15-55](#miscellaneous)

[15.5.2 Interactive electronic technical manuals
15-56](#interactive-electronic-technical-manuals)

[15.5.2.1 General 15-56](#general-4)

[15.5.2.2 Text 15-58](#text)

[15.5.2.3 Graphics 15-59](#graphics)

[15.5.2.4 Audio 15-61](#audio)

[15.5.2.5 Warnings, cautions, and notes
15-62](#warnings-cautions-and-notes-1)

[15.5.2.6 Interaction style 15-63](#interaction-style)

[15.5.2.7 User interface 15-65](#user-interface)

[15.5.2.8 Special requirements for proceduralized instructions
15-65](#special-requirements-for-proceduralized-instructions)

[15.5.2.9 Special requirements for troubleshooting information
15-66](#special-requirements-for-troubleshooting-information)

[15.5.2.10 Presentation of parts information
15-67](#presentation-of-parts-information)

[15.5.2.11 Descriptive information 15-68](#descriptive-information)

[15.6 Accommodating people with disabilities
15-68](#accommodating-people-with-disabilities)

[15.6.1 Document readability and handling
15-69](#document-readability-and-handling)

[15.6.2 Cognitive or language disabilities
15-70](#cognitive-or-language-disabilities)

[Glossary 15-71](#__RefHeading___Toc23642109)

[References 15-74](#__RefHeading___Toc23642110)

[Index 15-77](#__RefHeading___Toc23642111)

**List of exhibits**

[**Exhibit 15.4 FAA directives and order of document components**
**15-33**](#__RefHeading___Toc25028313)

[Exhibit 15.4.1.2 Type sizes for cover page elements
15-34](#__RefHeading___Toc25028314)

[Exhibit 15.4.12.3 (a) User Feedback form - Front
15-47](#__RefHeading___Toc25028315)

[Exhibit 15.4.12.3 (b) User feedback form - Back
15-48](#__RefHeading___Toc25028316)

#  User documentation

This section provides criteria and rules for the development of
documents that will be used by operators and maintainers in the
performance of routine and corrective use of systems and equipment. User
documentation includes user guides and manuals, user handbooks and
technical instructions, job performance aids, quick reference guides,
and instruction placards.

To be successful, a document must be appropriate to the knowledge and
skills of its users, to the tasks they will perform using the document,
and to the environment in which the users will perform these tasks. To
ensure success, document development might include the following steps:
(a) determine the relevant characteristics of the users of the document,
in particular, their existing knowledge and skills, (b) determine the
environment in which the document will be used, (c) determine the tasks
to be covered by the document, (d) determine the users\' information
requirements, (e) determine the appropriate types of documentation, (f)
create draft documents, (g) perform technical review(s), (h) perform
usability tests, and (i) prepare documentation for release.

User documentation is part of the interface between the users and other
system components. It contributes to the user\'s cognitive understanding
of the hardware, software, and human interactions with these other
components of the system. It can serve as a job aid and as a supplement
to (but not a substitute for) system training. Thus, this section
contributes to the usability and effectiveness of the operational system
and is to be applied to new systems and equipment acquisitions and
modifications as a part of development and procurement.

The first part of this section is devoted to criteria and rules for the
development of printed user documentation in general. These general
topics include organizing the document, writing the text, and laying out
the page. These topics are followed by criteria and rules for the
individual components that comprise a user document, such as the title
page, figures, instructions, and indexes.

## 15.1 General {#general .unnumbered}

The users of a document want the document to help them perform their
tasks quickly and efficiently. However, these users differ from each
other in many ways in level of expertise, in motivation, in time
constraints, in work styles, in reading abilities, in attitudes, in
personal preferences, in age, and so on. The more these differences are
accommodated, the more effective a document will be to its individual
users. This section recommends some ways to match documentation to users
and ways to make the documentation appear easy to use.

### 15.1.1 Matching documentation to users {#matching-documentation-to-users .unnumbered}

-   **15.1.1.1 Description of expected users.** The procuring agency
    shall provide a description of the expected users of the document to
    the document contractor. The description would include the following
    sorts of information: (a) aptitude profile, (b) reading level, (c)
    time in job, (d) job-related training, (e) job-related work
    experience, and (f) job-related skills, knowledge and duties. This
    description could be iterated between the procuring agency and the
    technical writers until they mutually agree that it is sufficient.
    \[Source: Joyce, R.P., Chenzoff, Mulligan, & Mallory (AFHRL-TR-73),
    1973; Department of Transportation (FAA-D-2494/b), 1984\]

    **Example.** FAA-D-2494/b, Technical Instruction Book Manuscript:
    Electronic, Electrical, and Mechanical Equipment, Requirements for
    Preparation of Manuscript and Production of Books, provides a
    general level description of some of these user characteristics, as
    well as instruction and maintenance environments.

-   **15.1.1.2** **Documentation for people at different skill levels.**
    If the users of a document are expected to vary widely in their
    skills and levels of experience, the document shall permit use in
    different ways by people at different levels, or different versions
    of the document shall be prepared for people at different levels. If
    a single document is designed for use by people with different skill
    levels, use by people at one level shall not be hindered by the
    material relevant to a different level. \[Source: FAA-D-2494/b,
    1984, Department of Defense (MIL-M-87268), 1995\]

**Examples.** Beginning users can be guided to a tutorial, help process,
or an entry-level document. Separate reference documents can be written
for beginners, advanced users, and experts. A document intended for
\"novices\" and \"power users\" of computer applications programs may
give a procedure to select a sequence of windows for the novices and
keyboard codes for direct control selection by the power users. Novice
users might be given detailed, step-by step instructions to complete a
procedure, while expert users might simply be given the name of the
procedure to be completed \-- a sort of checklist.

Another approach is to code information for different skill levels. Font
size and type, opposite or alternative pages or paragraphs, shaded or
color-coded boxes or borders, and position location on a page can be
used to indicate applicable skill levels. For instance, location coding
is typically used when multiple languages are presented for identical
instructions.

### 15.1.2 Making documentation appear easy to use {#making-documentation-appear-easy-to-use .unnumbered}

Some components of a document affect users\' perceptions of its
attractiveness and its apparent ease of use. These components are listed
here in their order of importance to users\' perceptions.

-   **15.1.2.1** **Tabs.** If a document has many divisions (5 or more),
    it should have tabs for each major division or for each frequently
    used division. \[Source: Angiolillo and Roberts, 1991; Simpson and
    Casey, 1988\]

    **Examples.** This document uses an edge tab on the side of the
    insert page. A bleed-through marking at the same edge location on
    each page in a section, chapter, or topic can mark and divide
    topics.

-   **15.1.2.2** **Guides to organization.** User documents should have
    informative titles and, if applicable, a discernable, hierarchical
    system of section headings. Different levels of headings should be
    differentiated with typographic cuing, for example, size and
    boldness of the type (see sections 15.2.1.1 and 15.3.3). White
    space, color, font type, and font sizes can be used judiciously if
    they aid in locating and categorizing information and contribute to
    readability and appearance of the document. They then result in a
    usable and friendly document. \[Source: Angiolillo and Roberts,
    1991\]

```{=html}
<!-- -->
```
-   **15.1.2.3** **Table of contents.** A user document shall have a
    table of contents unless it has fewer than three divisions or fewer
    than six pages. The table of contents shall not appear crowded, that
    is, it shall have a liberal amount of white space, and it shall use
    typographic cuing to differentiate among levels of headings.
    \[Source: Angiolillo and Roberts, 1991; FAA-D-2494/b, 1984; Simpson
    and Casey, 1988\]

```{=html}
<!-- -->
```
-   **15.1.2.4** **Figures and examples.** User documents should be
    generous in providing figures and examples. Information that can be
    effectively presented as a figure or exhibit, should be. \[Source:
    Angiolillo and Roberts, 1991\]

## 15.2 Writing user documentation {#writing-user-documentation .unnumbered}

This section contains criteria and rules for organizing a document, for
writing and presenting paragraphs and sentences, and for choosing and
using words and symbols, including abbreviations and acronyms.

### 15.2.1 Organization {#organization .unnumbered}

Good documentation has a clear conceptual organization. The organization
needs to be compatible with its purpose and understandable to its users.
The organization helps the users find relevant information in order to
carry out their functions and tasks. There are three major ways to help
the user understand the conceptual organization: (a) the use of titles
and headings, (b) the visual appearance of the document, and (c) a
hierarchical numbering system.

**Discussion.** The features of the document can be reviewed for input
by a user group early in its development. These users can contribute to
its conceptual organization.

This section includes rules on the use of a variety of techniques that
can help users use a document more effectively.

#### 15.2.1.1 Titles and headings

Titles and headings are of major importance to users; they help users
find relevant information, understand the organization of the document,
and maintain awareness of their location in the document.

**Definitions.** A **title** is a word or phrase that describes or
identifies the contents of a document or a portion of a document. A
**heading** is the title of an organizational subdivision of a document,
that is, a title that has hierarchical significance.

**Discussion.** Headings are usually set apart from the text to which
they refer in a way that indicates the hierarchical structure of the
document. This may be accomplished with the use of horizontal and
vertical spacing. In addition, headings are usually differentiated from
text typographically, for example, by the use of larger type size or
increased boldness, or both.

-   **15.2.1.1.1 Titles.** A document shall have a title, and its major
    subdivisions shall have headings. These titles and headings shall be
    brief, descriptive, and distinctive. That is, within the constraint
    of being as brief as possible, a title or heading shall identify the
    contents of the document or division with sufficient detail to
    distinguish it from similar documents or divisions. \[Source:
    FAA-D-2494/b, 1984; MIL-STD-962B, 1988\]

-   **15.2.1.1.2 Paragraph titles.** If practical, each paragraph shall
    have a title that identifies its contents. Paragraph titles are
    practical if they help users in finding relevant information, if
    they contribute to understanding the paragraph contents, or if the
    users desire them. \[Source: FAA-D-2494/b, 1984; Department of
    Defense (MIL-STD-962B), 1988; Department of Defense (MIL-STD-490A),
    1985\]

-   **15.2.1.1.3** **Uniqueness of titles.** Titles and headings shall
    not be repeated within a major division of a document. \[Source:
    FAA-D-2494/b, 1984; MIL-STD-490A, 1985\]

#### 15.2.1.2 Numbering of sections and subsections {#numbering-of-sections-and-subsections .unnumbered}

-   **15.2.1.2.1** **Decimal numbering.** The subdivisions of a document
    should be numbered in a way that reflects the organization of the
    document. This can be accomplished by: (a) assigning consecutive
    numbers to the major divisions of the document, beginning with 1 for
    the first, 2 for the second, and so on, (b) following this number
    with a period, (c) assigning consecutive numbers beginning with one
    to each subdivision, if any, of each major division and appending
    this number to that of the preceding division, (d) following this
    number with a period, and (e) continuing this process with any
    additional subdivisions until the paragraph level is reached. The
    final number should not be followed with a period. \[Source:
    FAA-D-2494/b, 1984; MIL-STD-490A, 1985\]

-   **15.2.1.2.2** **Itemization within a paragraph.** If it is
    necessary to identify individual items within a paragraph, they
    should be identified with lower case letters in parentheses so that
    they are not confused with the decimal numbering system. \[Source:
    MIL-STD-962B, 1988; MIL-STD-490A, 1985\]

-   **15.2.1.2.3** **Number of levels**. If possible, the numbering
    system should not exceed five levels, that is, the number of
    subdivisions from the document as a whole to its numbered paragraphs
    should not exceed five. When the material and its potential
    organization lend itself to fewer levels, four or three would be
    preferable. \[Source: MIL-STD-962B, 1988; MIL-STD-490A, 1985\]

    **Discussion.** There is no \"right\" number of subdivisions for a
    document; whatever makes sense to the user is right as long as he or
    she can use it without difficulty. However, any numbering system
    becomes increasingly unwieldy as the number of subdivisions
    increases. Five levels is considered a reasonable limit. A rule of
    thumb from memory research is that people can generally remember
    five plus or minus two items or chunks of information. From a design
    point of view, the preference is to accommodate many people, thus,
    use fewer categories.

####  {#section .unnumbered}

#### 15.2.1.3 Advance organizers {#advance-organizers .unnumbered}

Advance organizers have been shown to improve comprehension and
retention of material that is unfamiliar to readers.

**Definition.** An **advance organizer** is supplementary information
that is presented prior to the main body of information in which a user
is interested.

**Examples.** Tables of contents, introductory summaries, flow charts,
and adjunct questions are all advance organizers as long as they occur
before the targeted information.

-   **15.2.1.3.1** **When to provide advance organizers.** If users are
    likely to be relatively unfamiliar with the contents of a document,
    one or more advance organizers should be included. \[Source:
    MIL-STD-962B, 1988; MIL-STD-490A, 1985\]

    **Examples.** An introductory summary that states the main points or
    provides a framework for a document or a division of a document can
    be an effective advance organizer. A bulleted, advanced summary
    provides the user with a list of topics that can be easily scanned.
    Headings in the form of questions are also effective advance
    organizers. Any document of more than a few pages will probably
    benefit from a table of contents.

    In this document, introductory textual information, and in some
    instances even exhibit information, is given in the right hand
    column and is associated with high level (first and second section
    level) headings. This introductory information is presented to give
    some advanced organization, orientation, or usage limitations for
    the section contents. Such information is optional for lower level
    headings.

#### 15.2.1.4 Internal cross references {#internal-cross-references .unnumbered}

-   **15.2.1.4.1** **Minimize internal cross referencing.** Internal
    cross referencing should be minimized. Ways to do this include: (a)
    repetition of material, (b) sequential organization of the document,
    and (c) use of foldout pages so that needed material is visible
    simultaneously with any preceding material. \[Source: MIL-STD-490A,
    1985; Simpson and Casey, 1988\]

```{=html}
<!-- -->
```
-   **15.2.1.4.2** **Form of internal cross references.** Internal
    cross-references shall refer to subdivision or paragraph numbers,
    or, if numbering is not used, to the title of the subdivision or
    paragraph. Cross-references shall not be made to page numbers.
    \[Source: MIL-STD-490A, 1985; MIL-STD-962B, 1988; Zaneski, 1982\]

#### 15.2.1.5 Task versus list orientation {#task-versus-list-orientation .unnumbered}

Most user documents will probably be organized to facilitate the
performance of one or more tasks. Others might be intended to provide
quick access to specific information, and thus might be organized as
ordered lists. For some documents, a hybrid of the two organizations
might be appropriate (see section 15.5.1).

-   **15.2.1.5.1** **Task orientation.** If a task orientation is
    appropriate for a user document, the organization of the document
    should reflect the steps of the task as determined by a task
    analysis. If the document covers more than one task, the sequence of
    coverage should reflect the sequence in which the tasks are
    performed to the extent possible (see section 15.5.1 for procedural
    instructions). \[Source: Simpson and Casey, 1988\]

-   **15.2.1.5.2** **List orientation.** If a list orientation is
    appropriate for a user document, the document should be organized in
    a meaningful way, such as listing the topics in sequential, logical,
    or alphabetic order. \[Source: Gribbons, 1992\]

### 15.2.2 Paragraphs {#paragraphs .unnumbered}

-   **15.2.2.1** **Content of paragraphs.** In general, the content of a
    paragraph should be limited to a single idea. All of the material in
    the paragraph should relate to and develop that idea. \[Source:
    MIL-M-87268, 1995\]

-   **15.2.2.2** **Topic sentences.** In general, a paragraph should
    have a topic sentence, that is, a sentence that announces the topic
    of the paragraph. If present, a topic sentence should follow an
    initial linking sentence if there is one; otherwise, it should be
    the first sentence of the paragraph. \[Source: Spyridakis & Wenger,
    1992\]

    **Definition.** A **linking sentence** is a sentence that connects
    the paragraph it is in to the paragraph that precedes or follows it.
    The connection is usually accomplished by repeating a word or phrase
    or referring to a concept.

-   **15.2.2.3** **Length of paragraphs.** The average length of
    paragraphs in technical writing should not exceed six sentences.
    \[Source: MIL-M-87268, 1995\]

**Discussion.** The preferred length of paragraphs is three or four
sentences, but five or six sentences are acceptable.

### 15.2.3 Sentences {#sentences .unnumbered}

The ideal sentence states directly what is meant, using familiar words,
and without using any excess words; it states explicitly all information
that is to be communicated, leaving nothing to be inferred. \[Source:
Simpson and Casey, 1988\]

#### 15.2.3.1 Choice of wording

-   **15.2.3.1.1** **Clear, simple language.** The text of a document
    shall be written in clear, simple language, free of vague,
    ambiguous, unfamiliar, and unnecessary words. \[Source:
    FAA-D-2494/b, 1984; MIL-STD-490A, 1985; MIL-STD-962B, 1988\]

```{=html}
<!-- -->
```
-   **15.2.3.1.2** **Technical terms.** The text of a document should
    contain a minimum number of technical terms that require specialized
    knowledge to be understood unless those terms are needed to convey
    precise meaning. See section 15.2.4.6.1 for rules regarding the
    definition of such terms when they are used. \[Source: FAA-D-2494/b,
    1984\]

#### 15.2.3.2 Writing level, readability {#writing-level-readability .unnumbered}

There are a number of formulas that derive a measure of the readability
of text from word difficulty (usually based on word length and
familiarity) and sentence complexity (usually based on sentence length).
These summary metrics are useful in categorizing and evaluating reading
levels of instructional materials. They do not provide specific
suggestions to help in the writing of a unique technical document as
they are usually calculated after the writing is done. Unfortunately,
comprehendability metrics are not yet available.

**Discussion.** These summary metrics include the Flesch formula for
reading ease, the Dale-Chall formula, the Devereaux formula, The US Army
FORECAST readability formula, and the Gunning Fog Index. Readability is
usually expressed as a reading grade level. For example, a text might be
said to be readable at the eighth grade level.

-   **15.2.3.2.1** **Writing level.** The writing level of a document
    should be appropriate to the users of that document. In addition to
    editorial review, draft review by a user group will provide insight
    into a document\'s readability and ability to be comprehended.
    \[Source: FAA-D-2494/b, 1984, Boff and Lincoln, 1988\]

#### 15.2.3.3 Length {#length .unnumbered}

The typical sentence in user documentation expresses a single thought.
The length of the sentence will be whatever is appropriate to the
adequate expression of the thought. In some literary styles and
subjects, very long sentences that maintain clarity are acceptable.

-   **15.2.3.3.1** **Average length.** Generally speaking, in technical
    writing, the length of sentences (without lists) should not, on the
    average, exceed 20 words. \[Source: MIL-M-87268, 1995\]

    **Discussion.** The preferred average sentence length is 17 words or
    less, but up to 20 is acceptable. Shorter sentences are desirable if
    they express the intended message clearly and completely and comply
    with grammar rules.

    Very long sentences often include lists; these lists can usually be
    presented vertically, that is, with each item on a separate line,
    greatly reducing the apparent difficulty of such sentences. Lists
    are especially appropriate for ordered series of items such as the
    sequential steps needed to perform a task.

#### 15.2.3.4 Complexity {#complexity .unnumbered}

Complex and compound sentences are more difficult for users to
comprehend than are simple sentences.

-   **15.2.3.4.1** **Single thought.** In general, a sentence should
    express a single thought. \[Source: MIL-M-87268, 1992\]

-   **15.2.3.4.2** **Subordinate clauses.** A user document should
    contain relatively few sentences that have more than one or two
    subordinate clauses. In general, short, simple sentences should be
    substituted for complex and compound sentences. \[Source:
    MIL-STD-490A, 1985; Hartley, 1978\]

#### 15.2.3.5 Word order {#word-order .unnumbered}

-   **15.2.3.5.1** **Normal order.** In general, the elements of a
    sentence should be arranged in the following order: (a) subject, (b)
    verb, (c) object, (d) predicate object, and (e) indirect object.
    \[Source: AFHRL-TR-73, 1973\]

    **Example.** \"Human factors specialists want well-written
    documentation for the system users.\"

####  {#section-1 .unnumbered}

#### 15.2.3.6 Voice {#voice .unnumbered}

-   **15.2.3.6.1** **Active, not passive voice.** In general, sentences
    should be written in the active, not the passive voice. That is, the
    subject acts upon the predicate rather than the more complex
    arrangement where the subject is acted upon by the predicate.
    \[Source: FAA-D-2494/b, 1984; Department of Defense (MIL-HDBK-761A),
    1989; Simpson and Casey, 1988; Spyridakis & Wenger, 1992\]

    **Examples.** \"Lively sentences move readers\" (active) versus
    \"The readers are moved by lively sentences\" (passive).

#### 15.2.3.7 Person and mood {#person-and-mood .unnumbered}

-   **15.2.3.7.1** **Second person imperative.** The second person verb
    form and the imperative mood shall be used in all sentences that
    direct the reader to do something. Examples are: \"Remove test set
    from carrying case,\" and \"Turn R15 fully clockwise.\" \[Source:
    AFHRL-TR-73, 1973; FAA-D-2494/b, 1984\]

#### 15.2.3.8 Positive, not negative wording {#positive-not-negative-wording .unnumbered}

-   **15.2.3.8.1** **When to use positive wording.** Most of the time,
    positively worded sentences should be used because they are more
    definitive, less confusing, and less evasive than negatively worded
    statements. \[Source: Hartley, 1978; Simpson and Casey, 1988;
    Spyridakis & Wenger, 1992\]

    **Examples.** \"Often writers will not use negative sentences since
    these statements may not always be correctly interpreted\"
    (negative) versus \"Writers often choose the clarity of the positive
    over the confusion of the negative\" (positive). Consider: \"The
    operator monitoring for errors did not see the alarm nor solve the
    problem\" (negative) versus \"The operator failed to see the alarm
    or to act upon the problem\" (positive).

-   **15.2.3.8.2** **When to use negative wording.** Negative wording
    should be used to state prohibitions and to correct existing or
    potential misconceptions. \[Source: Hartley, 1978\]

    **Examples.** An example of a prohibition is: \"Do not remove the
    cover until the power cord has been unplugged.\" An example of
    correcting a potential misconception is: \"The highest voltage is
    not present in the largest wire; it is present in the red wire.\"
    Also consider: \"The alarm display was beyond the visual envelopes
    of the operators, thus the problem could not be detected by the
    operational system.\"

#### 15.2.3.9 Standard phrases {#standard-phrases .unnumbered}

-   **15.2.3.9.1** **Consistent phrases.** The same phrase should be
    used to express the same meaning throughout a document. For example,
    the phrase \"conforming to\" should not be used in one place and
    \"in accordance with\" in another if the same meaning is intended.
    \[Source: MIL-STD-490A, 1985; MIL-STD-962B, 1988\]

```{=html}
<!-- -->
```
-   **15.2.3.9.2** **Task steps.** If a task step occurs more than once
    in a user document, the same words shall be used in all occurrences,
    except for any unique variables that need to be included in the
    different occurrences. \[Source: AFHRL-TR-73, 1973\]

#### 15.2.3.10 Capitalization and punctuation {#capitalization-and-punctuation .unnumbered}

-   **15.2.3.10.1** **Capitalization.** The United States Government
    Printing Office *Style Manual* shall be used as a guide for
    capitalization. If the *Style Manual* does not provide the guidance
    needed, Merriam-Webster\'s *New International Dictionary* shall be
    used. \[Source: MIL-STD-490A, 1985; MIL-STD-962B, 1988\]

-   **15.2.3.10.2** **Capitalization of phrases for emphasis.**
    Capitalization shall not be used to emphasize phrases (see section
    15.3.3.7 for the recommended way to emphasize text). \[Source:
    MIL-STD-490A, 1985\]

    **Discussion.** Text other than single words is easiest to read and
    comprehend when it is presented in mixed case letters. Single words
    are recognized better when printed in all upper case letters.

-   **15.2.3.10.3** **Punctuation.** The United States Government
    Printing Office *Style Manual* shall be used as a guide for
    punctuation. If the *Style Manual* does not provide the guidance
    needed, Merriam-Webster\'s *New International Dictionary* shall be
    used. \[Source: MIL-STD-490A, 1985; MIL-STD-962B, 1988;
    FAA-D-2494/b, 1984\]

**Discussion.** Punctuation is an aid to accurate reading. Well-planned
sentences need little punctuation. If a sentence seems to need extensive
punctuation, it may need to be rewritten.

### 15.2.4 Words and symbols {#words-and-symbols .unnumbered}

#### 15.2.4.1 Consistency

-   **15.2.4.1.1** **Terminology.** Technical lexicons should be
    developed within and between system and subsystems acquisition
    programs that include common human components (individual users or
    work groups). This terminology should reflect user inputs and shall
    be consistently used in system design and in user document
    development. Consistency of nomenclature, operational, and
    maintenance terminology is necessary to ensure that human
    communication is feasible, straight forward, and clear. Lexicon
    development should be done as early as possible in an acquisition.
    It is best done before the writing of the user documentation has
    begun. Terminology should be consistent throughout a user document
    and among related documents. For example, the name of a part,
    including any modifying words, should be the same in explanatory
    text, in procedural steps, and in parts lists. \[Source:
    FAA-D-2494/b, 1984; MIL-STD-490A, 1985; Simpson and Casey, 1988\]

    **Discussion.** Variations in words and phrases, whether they occur
    intentionally for stylistic reasons or unintentionally through
    carelessness, incur a strong risk of confusing the reader.
    Consistent use of words and phrases may incur a slight risk of
    boredom, but it is not likely to cause confusion. If consistency is
    ensured in design, it is more likely to be reflected in the
    documentation. However, inconsistent use of lexicon among design
    components is likely to result in confusion and increase training
    burden for the users. This is particularly problematic when standard
    and accepted practice is not used in NDI or COTS subsystems and
    components. Such consistency needs to be considered as a criterion
    in the selection of COTS subsystems and in evaluating its hidden
    human and monetary costs for operations and maintenance. This
    consideration argues for closer relationships between the production
    and selection of user documentation and component selection and
    design and development.

#### 15.2.4.2 Short, high-frequency words {#short-high-frequency-words .unnumbered}

Short, simple, and frequently used words are easier for readers to
recognize and comprehend than are long, complex, and infrequently used
words. \[Source: Spyridakis & Wenger, 1992\]

-   **15.2.4.2.1** **High-frequency words.** If equivalent high
    frequency (familiar) and low-frequency (unfamiliar) words exist for
    a desired use, the high-frequency word should be used. For example,
    use would be a better choice than employ. \[Source: Spyridakis &
    Wenger, 1992\]

-   **15.2.4.2.2** **Short words.** If equivalent short and long words
    exist for a desired use, the short word should be used. For example,
    use would be a better choice than utilize. \[Source: Spyridakis &
    Wenger, 1992\]

-   **15.2.4.2.3** **Simple words.** If equivalent simple and complex
    words or terms exist for a desired use, the simple word or term
    should be used. \[Source: Spyridakis & Wenger, 1992\]

#### 15.2.4.3 Concrete, non-ambiguous words {#concrete-non-ambiguous-words .unnumbered}

-   **15.2.4.3.1** **Concrete versus abstract words.** Concrete words
    and terms should be used rather than abstract words and terms.
    \[Source: Spyridakis & Wenger, 1992; Hartley, 1978\]

    **Examples.** Consider: \"Maintenance for this system is poor\"
    (abstract) versus \"Maintenance records show that four computer
    components fail to meet reliability standards and the depot can not
    repair them. Expensive replacement components remain on back order.
    The system has been down for three weeks\" (concrete).

```{=html}
<!-- -->
```
-   **15.2.4.3.2** **Ambiguous words.** Ambiguous words and terms shall
    be avoided. \[Source: FAA-D-2494/b, 1984\]

    **Example.** The word replace could mean either \"remove an existing
    item and install a different one\" or \"reinstall an item.\" Thus
    replace by itself is ambiguous and must have additional or different
    words to make the meaning clear.

```{=html}
<!-- -->
```
-   **15.2.4.3.3** **Indefinite words and terms.** Indefinite words and
    terms such as and/or, suitable, appropriate, and etc. should not be
    used. \[Source: MIL-STD-962B, 1988\]

```{=html}
<!-- -->
```
-   **15.2.4.3.4** **Variations on flammable.** The words inflammable
    and uninflammable shall not be used. Flammable shall be used to
    describe a combustible object, and nonflammable shall be used to
    describe a noncombustible object. \[Source: MIL-STD-490A, 1985;
    MIL-STD-962B, 1988\]

#### 15.2.4.4 Standard words {#standard-words .unnumbered}

-   **15.2.4.4.1** **If, when, and where.** The word if should be used
    at the beginning of phrases that state conditions in which the
    passage of time and spatial location are not important, for example,
    \"If a fuse is blown, perform the tests prescribed for the circuit
    it protects.\" The word when should be used at the beginning of
    phrases in which the passage of time is important, for example,
    \"When the motor reaches a speed of 200 RPM.\" The word where should
    probably not be used to introduce a conditional phrase unless
    spatial location is important. \[Source: MIL-M-87268, 1995\]

```{=html}
<!-- -->
```
-   **15.2.4.4.2** **Shall, should, may, and will.** If the sentence
    structure permits, the word \"shall\" shall be used in sentences
    that state something the user must do. The word \"should\" shall not
    be used in instructions to users. The word \"may\" shall be used to
    express permission or non-mandatory options. The word \"will\" shall
    not be used for any of these purposes. \[Source: FAA-D-2494/b, 1984;
    MIL-STD-490A, 1985; MIL-STD-962B, 1988\]

#### 15.2.4.5 Pronouns {#pronouns .unnumbered}

-   **15.2.4.5.1** **Unambiguous referents.** Whenever a pronoun is
    used, the noun to which it refers shall be clear and unambiguous.
    \[Source: FAA-D-2494/b, 1984\]

    **Example.** The following demonstrates an ambiguous sentence:
    \"Whenever the author knows the reader, he or she benefits.\" The
    following statement is clearer: \"Whenever the author knows the
    readers, he or she can write to meet their needs.\"

#### 15.2.4.6 Definitions {#definitions .unnumbered}

-   **15.2.4.6.1** **What to define.** Technical terms, uncommon words,
    and common words that are used in unusual or special ways shall be
    defined in the text and also in an alphabetically-ordered glossary,
    if one exists. Using one such section assists the user in navigating
    to this reference information. \[Source: FAA Order 1700.8D, 1992\]

    **Discussion.** In FAA technical document practice, when several
    (about 10) new terms or abbreviations are used a glossary or, as
    applicable, a list of acronyms would be included.

-   **15.2.4.6.2** **When to define.** Words or terms that must be
    defined shall be defined immediately following their first
    occurrence in the text. \[Source: FAA Order 1700.8D, 1992\]

#### 15.2.4.7 Abbreviations and acronyms {#abbreviations-and-acronyms .unnumbered}

The benefit of abbreviations and acronyms is the saving of space; they
are shorter, more compact versions of the words or phrases they
represent. The cost of abbreviations and acronyms is a reduction in
reader comprehension and an increase in reader effort. \[Source: Simpson
and Casey, 1988\]

**Definitions.** An **abbreviation** is a shortened version of a word or
group of words formed by omitting one or more letters. An **acronym** is
a word formed from the initial letter or letters of a group of words.

**Examples.** \"ft\" is an abbreviation of foot and \"CAM\" is the
acronym for Computer-Aided Manufacturing.

-   **15.2.4.7.1** **Keep abbreviations and acronyms to a minimum.**
    Abbreviations and acronyms shall be kept to a minimum that is
    appropriate to the technical understanding and usage of the intended
    users. After its initial definition, an abbreviation or acronym
    shall be used whenever the term occurs. \[Source: FAA-D-2494/b,
    1984\]

    **Discussion.** Judgment is necessary to determine the technical
    understanding and when to use the technical vernacular appropriate
    to the target users. For example, if a technical document for
    maintenance personnel used the terms \"very high frequency
    omni-directional radio\" and \"baby N connector\" instead of VOR and
    BNC, the full names would be inappropriate. The full names may be
    appropriate for a lay audience, but they would be gibberish and
    distracting to the target users. There is no substitute for knowing
    or finding the users.

-   **15.2.4.7.2** **Definition of abbreviations and acronyms.**
    Abbreviations and acronyms shall be defined immediately following
    their first occurrence in the text. Their definitions shall consist
    of presenting the word or term fully spelled out, followed by the
    abbreviation or acronym enclosed in parentheses. Examples are:
    \"\...abbreviation (abbr)\...\", and \"\...Government Printing
    Office (GPO)\....\" \[Source: FAA-D-2494/b, 1984\]

-   **15.2.4.7.3** **Glossary.** The abbreviations and acronyms used in
    a document shall be listed alphabetically and defined in a glossary.
    \[Source: FAA-D-2494/b, 1984\]

-   **15.2.4.7.4** **Standard abbreviations and acronyms.** To the
    extent possible, abbreviations and acronyms shall be those given in:

a.  FAA Order 1000.15A, Glossary,

b.  FAA Order 7340.1H, Contractions, and

c.  ASME Y1.1, Abbreviations for Use on Drawings and in Text. \[Source:
    FAA-D-2494/b, 1984; Department of Transportation (FAA Order
    1000.15A), 1975; FAA Order 1700.8D, 1992; Federal Aviation
    Administration (FAA Order 7340.1H), 2000\]

-   **15.2.4.7.5** **Nonstandard abbreviations.** If a word or term to
    be abbreviated does not appear in any of the sources listed in
    paragraph 15.2.4.7.5, the word or term should be abbreviated in
    accordance with the United States Government Printing Office *Style
    Manual*. In specific specialized technical areas, technical sources,
    standards, and practice should be followed. \[Source: MIL-STD-962B,
    1988\]

    **Discussion.** In certain operating systems, upper and lower case
    letters can mean different things. For example, grep, Grep, and GREP
    have a different meaning in the UNIX operating system.

```{=html}
<!-- -->
```
-   **15.2.4.7.6** **Units of measurement.** The abbreviation and
    punctuation of units shall conform to ANSI/IEEE Standard 260 for
    standard letters and symbols for units on measurement. For
    additional abbreviation guidance conform to the United States
    Government Printing Office *Style Manual*. \[Source: FAA Order
    1700.8D, 1992\]

```{=html}
<!-- -->
```
-   
-   
-   

#### 15.2.4.8 Spelling {#spelling .unnumbered}

-   **15.2.4.8.1** **Spelling.** The United States Government Printing
    Office *Style Manual* shall be used as a guide for spelling. If the
    *Style Manual* does not provide the guidance needed, Merriam
    Webster\'s *New International Dictionary* shall be used. In
    equivalent spelling, the first citation shall be used. \[Source:
    FAA-D-2494/b, 1984; MIL-STD-490A, 1985; MIL-STD-962B, 1988\]

#### 15.2.4.9 Numbers {#numbers .unnumbered}

-   **15.2.4.9.1** **Numerals versus words.** Numbers representing
    measurements or time shall be expressed in numerals. Numbers (both
    cardinal and ordinal) representing quantities of 10 or more shall be
    expressed in numerals; those representing quantities less than 10
    shall be expressed in words. If a number is the first word in a
    sentence, it shall be expressed in words. Other cases and exceptions
    to these rules shall conform to the United States Government
    Printing Office *Style Manual*. \[Source: FAA-D-2494/b, 1984; U.S.
    Government Printing Office (USGPO Style Manual), 1984\]

    **Discussion.** This rule pertains to the decimal (base 10)
    numbering system, but in specific industry and technical areas other
    base systems may be used (for example: binary, hexadecimal, and
    octal systems).

```{=html}
<!-- -->
```
-   **15.2.4.9.2** **Arabic numerals.** In general, Arabic numerals
    should be used, not roman numerals. \[Source: USGPO Style Manual,
    1984\]

    **Exception.** Roman numerals are recommended for numbering the
    pages of any front matter a document might contain (see paragraph
    15.3.2.6.3).

-   **15.2.4.9.3** **Decimals versus fractions.** Non-whole numbers
    should be expressed as decimals, not fractions. \[Source:
    MIL-STD-962B, 1988\]

```{=html}
<!-- -->
```
-   **15.2.4.9.4** **Decimals and leading and trailing zeroes.**
    Decimals of less than one shall be written with a zero preceding the
    decimal point. Zeroes following a decimal shall be omitted unless
    they indicate exact measurement. \[Source: USGPO Style Manual,
    1984\]

#### 15.2.4.10 Units of measurement {#units-of-measurement .unnumbered}

-   **15.2.4.10.1** **Dual units.** Both the International System of
    Units (the Metric system) and the customary inch-pound units of
    measurement shall be included in text and exhibits. The customary
    units shall be given first, followed by the International System
    units in parentheses, for example, 36 in (91 cm). This document
    follows the accepted style for metric standards, which places metric
    values first. The abbreviation and punctuation of units shall
    conform to ANSI/IEEE Standard 260 and to the United States
    Government Printing Office *Style Manual*. \[Source: FAA Order
    1700.8D, 1992\]

-   **15.2.4.10.2** **Conversion of units.** The conversion of units
    between the International System and the customary inch-pound system
    shall conform to ANSI/IEEE Standard 268, Metric Practice, and to
    FED-STD-376. \[Source: MIL-STD-962B, 1988\]

#### 15.2.4.11 Letter symbols and mathematical signs {#letter-symbols-and-mathematical-signs .unnumbered}

-   **15.2.4.11.1** **Letter symbols and mathematical signs.** Letters
    used as symbols for objects and mathematical signs shall be in
    accordance with ANSI/IEE 260. \[Source: FAA-D-2494/b, 1984\]

#### 15.2.4.12 Graphic symbols {#graphic-symbols .unnumbered}

-   **15.2.4.12.1** **Standard graphic symbols.** Graphic symbols used
    for circuit elements shall be those contained in ANSI Y32.2 and
    ANSI/IEEE 315A with the following additional provisions: (a) in
    those cases in which ANSI Y32.2 gives different symbols for
    electronic and electrical elements, the symbols for electronic
    elements shall be used, (b) under items 4.3.1 to 4.3.3, 4.3.5 to
    4.3.7, 4.25.3, and 4.30.2, the parallel line contact symbols shall
    not be used, and (c) under items 11.2.7 and 11.2.7.1, the circular
    symbol for indicator lights shall not be used. Designations for
    electrical diagrams, power switches, and controls shall conform to
    ANSI Y32.16, Reference Designations for Electrical and Electronic
    Diagrams and MIL-STD-27A, Designations for Electrical Power Switch
    Devices and Industrial Control Devices. \[Source: FAA-D-2494/b,
    1984\]

-   **15.2.4.12.2** **Mechanical diagram symbols.** Graphic symbols
    designating mechanical parts on diagrams and line drawings shall be
    in accordance with MIL-STD-17B as applicable. \[Source:
    FAA-D-2494/b, 1984\]

-   **15.2.4.12.3** **Logic diagram symbols.** Graphic symbols used in
    logic diagrams shall be in accordance with ANSI/IEEE 91. Graphic
    symbols not listed in ANSI/IEEE 91 shall not be used without
    approval of the acquisition program office. \[Source: FAA-D-2494/b,
    1984\]

#### 15.2.4.13 Other symbols {#other-symbols .unnumbered}

-   **15.2.4.13.1** **Flow chart symbols.** Symbols used in flow charts
    shall be in accordance with ANSI/ISO 5807. \[Source: FAA-D-2494/b,
    1984\]

    **Discussion.** Flow charts are seldom used in present software
    development which use pseudo code and other charts.

-   **15.2.4.13.2** **Special symbols.** Special symbols used in
    diagrams shall be explained as follows: (a) if the use of a special
    symbol is limited to a diagram, the symbol shall be defined in the
    diagram in which it appears, (b) if special symbols are used
    extensively, the symbols shall be defined in a chart on a separate
    page in a section that provides support data, and (c) preexisting
    charts that define symbols in addition to those that actually appear
    in the document shall not be used. \[Source: FAA-D-2494/b, 1984\]

## 15.3 Layout and formatting {#layout-and-formatting .unnumbered}

The most appropriate physical structure for a document depends upon how
it will be used. Who will use the document? In what environment will it
be used? For what tasks or purposes will it be used? Another important
consideration is the handling of updates to the document.

### 15.3.1 Document-level considerations {#document-level-considerations .unnumbered}

#### 15.3.1.1 Size

The optimum size for the pages of a document depends primarily upon the
circumstances of its use. For example, a good size for a simple job
performance aid might be a size that would fit in a pocket, or a good
size for a user\'s guide to a large, complex system might be 8.5 by 11
inch (21.6 by 27.9 cm) pages.

-   **15.3.1.1.1** **Basic size.** The basic page size for user
    documents should be 8.5 inches (21.6 cm) wide by 11 inches (27.9 cm)
    high. If these pages are trimmed prior to binding, the finished size
    should be at least 8.25 by 10.75 inches (21.0 by 27.3 cm). \[Source:
    FAA-D-2494/b, 1984\]

-   **15.3.1.1.2** **Avoidance of odd sizes.** Odd sizes and shapes
    should be avoided, for example, pages that are very large or very
    small, pages that have extreme height-to-width ratios, and pages
    that are wider than they are high. \[Source: Simpson and Casey,
    1988\]

#### 15.3.1.2 Binding {#binding .unnumbered}

The type of binding appropriate for a document depends largely on the
user\'s priorities and on the way in which the document will be used.
The primary considerations are whether or not users will want the
document to lie flat when opened (see paragraph 15.3.1.2.2) and whether
or not individual pages of the document will be removed and new pages
inserted (see paragraph 15.3.1.2.3).

**Definitions.** In **mechanical binding**, the pages are punched with
either round or slotted holes and then placed in a ring binder or bound
with a comb or spiral binder. In **perfect binding**, the pages are
assembled, the left side is cut and roughed, glue is applied, and the
cover is attached to the pages. In **pamphlet binding**, the pages are
stitched or stapled together. There are two types of pamphlet binding,
saddle stitched and side stitched. **Saddle stitching** permits the
document to lie flat.

-   **15.3.1.2.1** **Page orientation.** Unless special considerations
    warrant a different orientation, pages should be bound at the left
    side, not at the top. \[Source: Simpson and Casey, 1988\]

-   **15.3.1.2.2** **Flat-lying.** The binding should permit the
    document to lie flat when it is open. \[Source: Simpson and Casey,
    1988\]

    **Discussion.** Ring binders and comb or spiral binding are probably
    the best choices in this respect for large documents; saddle
    stitching, for small documents. Spiral and comb bindings are
    cheaper; ring binders permit easy access for copying as well as
    updates.

-   **15.3.1.2.3** **Easy updating.** If it is likely that a document
    will be updated frequently, a ring binder should probably be
    selected. \[Source: Simpson and Casey, 1988\]

### 15.3.2 Page-level considerations {#page-level-considerations .unnumbered}

It is desirable that the visual structure of a document, that is, its
cues and format, is reflected and complemented by the structure in the
table of contents. The primary objective of the text designer is to
create a visual hierarchy that distinguishes major concepts from
sub-concepts and one category of information from another. Ways to do
this include varying the size of type and the position of the material
on the page. Visual cues are most effective when used sparingly.

#### 15.3.2.1 Margins

-   **15.3.2.1.1** **Consistency.** Margins shall be consistent
    throughout a document, or, conversely, the portion of the page used
    to present information shall be consistent. \[Source:
    Houghton-Alico, 1985\]

-   **15.3.2.1.2** **Pages 8.5 by 11 inches (21.6 by 27.9 cm) or
    larger.** On pages 8.5 by 11 inches (21.6 by 27.9 cm) or larger, the
    margins shall be at least 1 inch (2.54 cm) on all sides. \[Source:
    FAA-D-2494/b, 1984; FAA Order 1700.8D, 1992; Simpson and Casey,
    1988\]

    **Discussion.** This margin recommendation permits room for binding
    or for punched holes for loose-leaf ring binders on all pages
    without the necessity of special or offset margins for reference
    documents. FAA Order 1320.1.D sets the text line presentation area
    as 7 in (18.8 cm) width for directives. FAA-D-2494/b (for
    instruction books with right and left hand pages) sets margins at
    .75 in (1.9 cm) on the outside edges and 1 in (2.5 cm) on the inside
    edges as margins for instruction books.

-   **15.3.2.1.3** **Offset for binding.** If the pages are to be bound
    on the left, the left margin shall be increased by 0.5 inch (1.3 cm)
    for 8.5 by 11 inch (21.6 by 27.9 cm) pages or by an amount
    proportional to the ratio of the page width to 8.5 inches (21.6 cm)
    for pages of other sizes. \[Source: Simpson and Casey, 1988\]

#### 15.3.2.2 Headers and footers {#headers-and-footers .unnumbered}

Page headers and footers can be used to present a variety of potentially
useful information to the reader, for example, page numbers, the name of
the section and possibly also the subsection of the document, and the
date of issue of the page or document.

-   **15.3.2.2.1** **Use of headers and footers.** If only a few
    elements of information are to be presented, they should probably be
    presented in a header only; that is, a footer should be omitted. If
    more elements are to be presented than fit comfortably in a header,
    then the information should be divided between a header and a
    footer. \[Source: Simpson and Casey, 1988\]

-   **15.3.2.2.2** **Location of information within a header or
    footer.** The elements of information included in headers and
    footers should be located in accordance with their importance to the
    reader. The most important elements should be located at the outside
    ends. The next most important elements should be located either
    centered or near the outside end of the header or footer. The least
    important information should be presented at the inside end.
    \[Source: Simpson and Casey, 1988; Houghton-Alico, 1985\]

-   **15.3.2.2.3** **Headers, footers, and margins.** Headers and
    footers should be located within the space reserved for top and
    bottom margins, that is, they should not take space away from that
    reserved for the body of the document. \[Source: FAA-D-2494/b,
    1984\]

#### 15.3.2.3 White space {#white-space .unnumbered}

The spatial formatting of text can be extremely effective in
communicating the structural hierarchy of information. The consistent
and logical allocation of vertical and horizontal white space creates a
visual hierarchy that separates major headings from minor headings,
headings from text, and so forth. The judicious use of spacing can
convey information about the structure of a document to users more
easily and effectively than can typographic cues. White space can be
used in combination with typographical cues. Reduced line lengths and
associated horizontal white space can make skimming, searching, and
reading easier. \[Source: Gribbons, 1992; Hartley, 1978\]

-   **15.3.2.3.1** **Representational vertical spacing.** The vertical
    space that precedes a text element should indicate that element\'s
    level in the document\'s structural hierarchy, with the amount of
    space increasing at each level. \[Source: Gribbons, 1992\]

    **Example.** A logical point to start in determining vertical
    spacing is the smallest vertical unit, the space between two lines
    of text. If this space is taken to be one unit of spacing, the
    resulting representational spacing might be two units between
    paragraphs, four units between a subheading and a paragraph, and
    eight units between a major heading and a subheading. This document
    uses vertical white space to set off text paragraphs in the right-
    hand text columns. In the left column, white space combines with
    typographical cues to differentiate subsection heading levels.

-   **15.3.2.3.2 Horizontal spacing (indentation).** Horizontal spacing
    (indentation) is an alternative to vertical spacing as a means for
    showing the hierarchical structure of a document. If horizontal
    spacing is used, the left-most position should represent the highest
    level of the hierarchy, with subsequent indentations representing
    successively lower levels. \[Source: Gribbons, 1992\]

    **Discussion.** Horizontal spacing is not as straightforward as
    vertical in indicating hierarchical levels. While successive
    indentation would seem to imply successively lower hierarchical
    levels, readers perceive centered headings to be more important than
    headings at the left margin.

#### 15.3.2.4 Right-and left-hand pages {#right-and-left-hand-pages .unnumbered}

The printing of pages on both sides introduces the possibility and
desirability of treating the fronts of pages differently from the backs.
If offsets for binding are necessary, left- and right-hand pages will
have different margins (see paragraph 15.3.2.1.3).

**Definitions.** The terms **right-hand page** and **left-hand page**
have meaning only if pages are printed on both sides. In that case, a
right-hand page is the page printed on the front, and a left-hand page
is the page printed on the back. Thus, when the pages are bound, and the
document is open, the right-hand page appears on the right, and the
left-hand page appears on the left.

-   **15.3.2.4.1 Major divisions of the document.** Major divisions of
    the document should begin on right-hand pages. This will
    occasionally result in a blank left-hand page. \[Source:
    FAA-D-2494/b, 1984\]

    **Discussion.** In large frequently-used reference documents with
    many pages and divisions, one consistently begins each new major
    division on a right-hand odd-numbered page. This practice permits
    one to number pages within each section and to insert tabs between
    sections.

```{=html}
<!-- -->
```
-   **15.3.2.4.2** **Page numbering of left and right handed pages.**
    Right-hand pages shall be odd-numbered pages, and left-hand pages
    shall be even-numbered pages. \[Source: FAA-D-2494/b, 1984\]

#### 15.3.2.5 Page numbering {#page-numbering .unnumbered}

There are two common methods for numbering the pages in a document, (a)
numbering the pages sequentially from the beginning to the end of the
document, and (b) numbering the pages independently within each major
division of the document.

This second method incorporates a designation for the division into the
page number, for example, 3-9 would be the number of the ninth page of
the third division.

**Discussion.** Numbering within divisions has two advantages: (a) it
provides the reader with an additional location cue as to which division
one is looking at, and (b) it makes updating easier in that fewer pages
need be renumbered when material is added or deleted.

-   **15.3.2.5.1** **Arabic numerals.** Arabic numerals shall be used
    for the page numbers of the main body of a document. \[Source:
    FAA-D-2494/b, 1984; MIL-STD-962B, 1988\]

```{=html}
<!-- -->
```
-   **15.3.2.5.2** **Numbering style - body.** The page numbering style
    for the main body of documents containing three or more major
    divisions or having an average division length of six or more pages
    should be the division designation followed by a dash followed by
    the number of the page within the division, for example, 4-7 is the
    divisional page number of the seventh page of the fourth division.
    \[Source: FAA Order 1700.8D, 1992; Simpson and Casey, 1988\]

-   **15.3.2.5.3** **Numbering style - front material.** The pages of
    material at the beginning of a document, such as a foreword or a
    table of contents, should be numbered sequentially with lower case
    roman numerals. \[Source: FAA Order 1700.8D, 1992; FAA-D-2494/b,
    1984; MIL-STD-962B, 1988\]

-   **15.3.2.5.4** **Numbering style - Appendixes.** Appendixes should
    be designated using consecutive letters beginning with A. Pages
    within an appendix should be numbered using the designation of the
    appendix followed by a dash followed by the sequential number of the
    page within the appendix, for example, A-3 would be the third page
    of Appendix A. \[Source: FAA Order 1700.8D, 1992\]

```{=html}
<!-- -->
```
-   **15.3.2.5.5 Location.** If compatible with other information
    displayed in headers and footers, page numbers shall be located at
    the bottom outside edge of the page, that is, at the right edge of
    right-hand pages and the left edge of left-hand pages. \[Source:
    FAA-D-2494/b, 1984\]

#### 15.3.2.6 Columns {#columns .unnumbered}

-   **15.3.2.6.1** **Number of columns.** The number of columns of text
    on a page of user documentation shall not exceed two. \[Source: FAA
    Order 1700.8D, 1992\]

    **Discussion.** The use of columns may seem to complicate word
    processing in certain software packages. However, the benefits of
    location coding permitted by appropriate white space to the user
    navigation and readability warrant consideration of columns from a
    human factors usability standpoint.

    **Discussion.** Since the division of the page into two columns
    halves the horizontal distance available for successive levels of
    indentation without affecting the vertical space available, the
    vertical spacing method will usually work more effectively than the
    horizontal.

#### 15.3.2.7 Foldout pages {#foldout-pages .unnumbered}

Foldout pages are relatively expensive to produce and relatively
difficult to handle. Still, there are advantages to their use; in
particular, the larger size may be necessary to display detail legibly.
They can also permit a drawing or table to be visible while the user
looks at other parts of the document.

-   **15.3.2.7.1** **Minimize use.** The use of foldout pages should be
    minimized to those necessary to legible display of the information
    and necessary to understanding and tracing location and relational
    information. \[Source: MIL-STD-490A, 1985; MIL-STD-962B, 1988\]

    **Discussion.** One way to reduce their use is to divide a large
    figure or table and display it on facing pages rather than printing
    it on an oversize page. When facing pages or fold out pages are used
    it may be necessary to aid the reader in tracing lines across the
    gaps or folds. For instance, when a large number of parallel lines
    transition across folds or gap, color coding of each continuing line
    may help a user trace and maintain the identity of the lines. Giving
    lines number or letter identifiers at places throughout each line
    may help.

```{=html}
<!-- -->
```
-   **15.3.2.7.2** **Foldout to the right.** Foldout pages shall fold to
    the right only; they shall not fold out to the top or bottom.
    \[Source: FAA Order 1700.8D, 1992\]

-   **15.3.2.7.3** **Visibility of page number and caption.** Each
    foldout page shall be folded so that the page number and the page
    caption are visible without unfolding. \[Source: FAA Order 1700.8D,
    1992\]

-   **15.3.2.7.4** **Visibility of entire exhibit.** If it is necessary
    that a user see an entire exhibit while reading another part of the
    document, the exhibit shall be printed with a blank area the size of
    a normal page at the left of the foldout page so that when the page
    is unfolded, the entire exhibit will be visible. \[Source: FAA Order
    1700.8D, 1992\]

```{=html}
<!-- -->
```
-   **15.3.2.7.5** **Location of foldout pages.** If the ratio of text
    to foldout pages is reasonably balanced, a foldout page should be
    the next page after the one on which it is mentioned. If doing this
    would result in an excessive amount of white space on text pages,
    the foldout pages should be grouped together in a single section
    immediately preceding any appendixes. \[Source: FAA Order 1700.8D,
    1992; MIL-STD-490A, 1985; MIL-STD-962B, 1988\]

**Discussion.** If a document contains both foldout and non-foldout
exhibits of the same type and the foldout exhibits are grouped at the
end of the document, users may have difficulty finding a particular
exhibit. Treating the foldout exhibits as a separate category of
exhibits will help alleviate the difficulty. For example, exhibits that
are integrated into the text might be called \"exhibits\" and oversize
exhibits that are grouped at the end might be called \"foldouts.\"

### 15.3.3 Typographic issues {#typographic-issues .unnumbered}

Typographic cues are useful for conveying to readers the importance and
organization of textual material. Type size is easily the most important
cue. The position of material such as headings is another potential cue,
as is the use of all capital letters. The use of color and varied
intensity (boldness) of printing are additional potential cues.

**Definition.** A **point** is a measure of the height of type; there
are 72 points in an inch (2.54 cm).

#### 15.3.3.1 Type size

-   **15.3.3.1.1** **Basic size.** The basic size for text should be 10
    point type. If the document will be used under dim illumination, the
    size should be increased to 11 or 12 points. \[Source: FAA Order
    1700.8D, 1992; FAA-D-2494/b, 1984; Zaneski, 1982\]

    **Discussion.** This rule assumes that the document will be composed
    and reproduced with good quality equipment resulting in sharp, clear
    images, and that it will be viewed under satisfactory conditions,
    including illumination, reading distance, and viewing angle.

    **Examples.** The text of this document is 12 point type. Newspaper
    text is 10 point. Eight point type is often used in car
    advertisements. Smaller sizes are used in phone book listings and
    tabular materials.

-   **15.3.3.1.2** **Minimum size.** The minimum size for text should be
    8 point type. This size should be used only when viewing conditions,
    particularly illumination, are satisfactory. \[Source: FAA-D-2494/b,
    1984\]

-   **15.3.3.1.3** **Unequal spacing of sizes.** If more than two type
    sizes are used to indicate the importance of material, for example,
    the level of a heading, the difference in size from one level to the
    next should increase as the size of the type increases; that is, the
    differences should not be equal. \[Source: Gribbons, 1992; Williams
    & Spyridakis, 1992\]

    **Example.** If three type sizes are used to indicate three levels
    of headings, the smallest size might be 12 points; the middle size,
    14 points; and the largest size, 18 points, rather than sizes of 12,
    14, and 16 points.

#### 15.3.3.2 Line length {#line-length .unnumbered}

Most readers prefer line lengths within the range of 14 to 36 picas for
type sizes in the range of 8 to 12 points, and lines varying within this
range are approximately equal in legibility. \[Source: Simpson and
Casey, 1988\]

**Definition.** A **pica** is the unit of measurement used in printing.
It is equal to 0.17 inch (4.23 mm).

-   **15.3.3.2.1** **Line length.** For type sizes in the range of 8 to
    12 points, line length should not be less than 14 picas or more than
    36 picas. \[Source: Simpson and Casey, 1988\]

    **Discussion.** Lines longer than 36 picas become increasingly
    difficult to read.

#### 15.3.3.3 Line spacing {#line-spacing .unnumbered}

-   **15.3.3.3.1** **Minimum spacing.** The spacing between lines using
    type sizes in the range of 8 to 12 points should be at least two
    points. \[Source: Simpson and Casey, 1988\]

    **Discussion.** If the space between lines is too small, reading
    difficulty is increased.

#### 15.3.3.4 Justification {#justification .unnumbered}

The alignment of the starting point of lines of text is generally agreed
to aid reading, probably by providing a predictable place for the eye to
move to. Most typeset text and much of the text produced with word
processors incorporates variable spacing within and between words so
that lines are of equal length and the right ends of the lines are also
aligned. In addition to variable spacing, words are often broken
(hyphenated) in the process of constructing equal length lines. There is
no evidence that the use of equal length lines aids reading, however,
hyphenation can cause reading difficulties.

**Definitions.** In **left-justified text**, lines of text are aligned
at the left, but spacing within and between words is not varied,
resulting in a ragged right margin. In **right-justified text**, lines
of text are aligned at the right, but spacing within and between words
is not varied, resulting in a ragged left margin. In **center-justified
text**, lines are centered on the page, with both right and left margins
ragged. In **fully-justified text**, spacing is added within and between
words so that all lines are the same length, resulting in alignment of
both right and left margins.

-   **15.3.3.4.1** **Justification of text.** For extended text, the
    type of justification used should be either left- or
    full-justification. Center- and right-justification should not be
    used for text. \[Source: Simpson and Casey, 1988\]

-   **15.3.3.4.2** **Appropriate use of right-justification.** If
    right-justification is used, its use should be restricted to such
    items as headings and information in headers and footers. \[Source:
    Simpson and Casey, 1988\]

-   **15.3.3.4.3** **Avoiding hyphenation.** The breaking of words
    between syllables at the ends of lines should be avoided. The only
    hyphens at the ends of lines of text should be those that properly
    signify compound words. \[Source: Simpson and Casey, 1988\]

#### 15.3.3.5 Type style (font) {#type-style-font .unnumbered}

Most type fonts fall into one of two categories, those having serifs and
those that do not (sans serif fonts). Readers seem to prefer fonts with
serifs and seem to read them more easily. \[Source: Cooper, Daglish, and
Adams, 1979; Simpson and Casey, 1988\]

**Definitions**. **Serifs** are decorative elements (short lines, knobs,
and balls) at the ends of the strokes that form letters. Sans serif
fonts do not have these decorative elements. A **type family** is a
collection of fonts that are similar in design but vary in size and
boldness. A family can include *italic* versions.

**Discussion.** By far the majority of books and newspapers use fonts
with serifs for the body text. Helvetica, Arial, and Univers are common
sans serif fonts. Sans serif fonts are often used for labels and
headings.

-   **15.3.3.5.1** **Serifs for basic font.** The basic font for a
    document body should be a font that has serifs. \[Source: Simpson
    and Casey, 1988\]

-   **15.3.3.5.2** **Minimize different fonts.** The number of different
    fonts used in a document should be kept to a minimum. \[Source:
    Simpson and Casey, 1988\]

    **Discussion.** One family of fonts can be used for text, including
    different sizes of type, boldface fonts, and italic fonts. Another
    family might be used to make another type of information stand out
    from the basic text.

#### 15.3.3.6 Upper versus mixed case text {#upper-versus-mixed-case-text .unnumbered}

Text that is written using both upper and lower case letters is both
preferred by users and more legible to them. In the case of isolated
letters and words, however, capital letters are more legible than lower
case letters. Logically this implies that all text, including titles,
headings, headers, and footers, would best be printed in mixed case.
However, the use of all upper case letters can make individual words
stand out and thus aid comprehension. \[Source: Gribbons, 1992; Simpson
and Casey, 1988\]

-   **15.3.3.6.1** **Words to be typed in upper case letters.** If the
    following words are used as headings, they shall be displayed in all
    upper case letters: (a) WARNING, (b) CAUTION, and (c) NOTE.
    \[Source: AFHRL-TR-73, 1973; FAA-D-2494/b, 1984\]

```{=html}
<!-- -->
```
-   **15.3.3.6.2** **Minimize use of upper case letters.** The use of
    upper case letters for words and phrases in text should be
    minimized; upper case letters should not be used to emphasize a word
    or phrase. \[Source: MIL-STD-962B, 1988; Hartley, 1978\]

#### 15.3.3.7 Typographic emphasis {#typographic-emphasis .unnumbered}

There are a variety of ways in which portions of text can be emphasized
typographically. The use of upper case letters has already been
discussed. Other commonly-used ways include: (a) the use of **boldface**
type, (b) the use of *italic* type, and (c) the use of
[underlining]{.underline}. The intent of all of these is to make a
portion of text stand out from its surroundings. \[Source: Simpson and
Casey, 1988\]

Judicious use of typographic emphasis can help readers locate and
remember things, but emphasis is probably most effective when it is used
sparingly. For emphasis to be effective, the reader must (a) be aware of
the intent of the emphasis, and (b) know enough about the task to judge
the importance of the emphasized words.

-   **15.3.3.7.1** **Inform the reader.** If typographic emphasis is
    used, the reader shall be informed of what it is and what it means.
    \[Source: Simpson and Casey, 1988\]

-   **15.3.3.7.2** **Use boldface type for emphasis.** If typographic
    emphasis is used, it shall be boldface type. \[Source: Hartley,
    1978; Simpson and Casey, 1988; Zaneski, 1982\]

-   **15.3.3.7.3** **Use typographic emphasis sparingly.** Typographic
    emphasis shall be used sparingly. \[Source: Hartley, 1978; Simpson
    and Casey, 1988\]

```{=html}
<!-- -->
```
-   **15.3.3.7.4** **Do not use underlining for emphasis.** Underlining
    should not be used for typographic emphasis. \[Source: FAA-D-2494/b,
    1984; MIL-STD-490A, 1985; MIL-STD-962B, 1988; Gribbons, 1992;
    Hartley, 1978; Simpson and Casey, 1988\]

    **Discussion.** Underlining actually makes the underlined text more
    difficult to read, at least for some readers; it reduces the white
    space between lines, and it disrupts the characteristic shape of the
    underlined word or words. The same is true for numbers.

    Sometimes underlining is use to indicate changes in a document.
    Other typographical cues such as redlining, asterisks, or vertical
    lines in the margin may be used to indicate changes. FAA order
    1320.1D calls for the use of asterisks or vertical lines in the
    margins to indicate change. Whatever the method, the notation for
    change should be explained in the text. In a directive, it is
    explained in a paragraph entitled explanation of changes.

```{=html}
<!-- -->
```
-   **15.3.3.7.5** **Do not use italics for emphasis.** Italic type
    shall not be used for typographic emphasis. \[Source: Hartley,
    1978\]

    **Discussion.** Italic type fonts are usually drawn with relatively
    thin lines, which tend to make these fonts recede rather than stand
    out from the surrounding text. This is the opposite of emphasis.
    Italic type is appropriate for the titles of books when they appear
    in text and in bibliographic references.

```{=html}
<!-- -->
```
-   **15.3.3.7.6** **Do not use upper case letters for emphasis.** All
    upper case letters should not be used for typographic emphasis in
    text. \[Source: MIL-STD-490A, 1985; Simpson and Casey, 1988\]

    **Discussion.** The use of all upper case letters in text slows
    reading and appears to interfere with memory of the unemphasized
    material. Individual words can be recognized faster when they appear
    in upper case letters, so, if used sparingly and wisely, upper case
    letters can be effective for emphasis. However, because boldface
    type has fewer actual and potential problems, it seems a better
    choice for typographic emphasis. FAA Order 1320.1D addresses the use
    of underlining and capital letters when standard typewriting is used
    for document preparation. It also notes that word processing
    equipment offers bold and other typographical cues which, when
    appropriately used, enhance reading and navigation in a document.

#### 15.3.3.8 Print contrast, quality {#print-contrast-quality .unnumbered}

Typesetting and competent offset printing produce print of adequate
quality for documents that may be used in a range of viewing conditions.
Modern laser printers can also produce print of this quality. Mechanical
or dot matrix printers generally do not produce print of this quality.
\[Source: Simpson and Casey, 1988\]

**Definition.** **Print contrast** is the ratio of the difference in
brightness between the printing and its background to the brightness of
the background (assuming dark print on a light background). It is
defined by (B1-B2)/B1, where B1 is the brighter of the two.

-   **15.3.3.8.1** **Adequate print contrast.** The print contrast of a
    document shall be high enough so that users can read it without
    eyestrain under the expected viewing conditions. \[Source: Simpson
    and Casey, 1988\]

#### 

#### 15.3.3.9 Color and shading

Color can be a very effective cue, especially when it is used to aid
users who are searching for something. However, users perceive color as
less significant than other types of typographic cuing, particularly
size and boldness. In addition, the existence of deficiencies in the
color vision of some users limits the applicability of color as an
effective cue. \[Source: Gribbons, 1992\]

-   **15.3.3.9.1** **Color as a typographic cue.** If color is used as a
    typographic cue, it shall be redundant with another typographic cue,
    such as size. \[Source: Gribbons, 1992\]

-   **15.3.3.9.2** **Text in color.** If color is used for either print
    or background, it shall satisfy the print contrast criterion,
    paragraph 15.3.3.8.1. \[Source: Gribbons, 1992\]

-   **15.3.3.9.3** **Subsequent reproduction.** If a document is likely
    to be photocopied, colors and shadings shall be selected so that
    their meanings do not become lost or distorted when photocopied.
    \[Source: Hartley, 1978; FAA-D-2494/b, 1984\]

**Discussion.** Colors that are clearly different in their original
reproduction may change during photocopying in black and white in ways
that change their meaning. For example, the lighter of two colors may
become the darker of two shades of gray. Similarly, gradients of colors
or shadings that are clear in the original production may be lost in
photocopying.

## 15.4 Components of documents {#components-of-documents .unnumbered}

This section contains rules for the various components that might be
contained in a user document, such as the cover page, table of contents,
and figures. Exhibit 15.4 lists FAA directives associated with certain
types of documents that are oriented to FAA users and lists the
components and the sequence for components, when applicable for each
type. These directives and related specifications listed in Exhibit 15.4
also call for mandatory items: forms to identify and control changes and
some explicitly required paragraphs and text. These mandatory policies
are to be followed for each applicable type of document.

**Discussion.** FAA Order 1320.1D addresses directives in general and
includes long orders (more than 25 pages) which may be called handbooks.
The order describes the orders development process and prescribes some
formal formatting details for organizational-level orders or
supplements. FAA Order 1320.58 addresses Maintenance Technical Handbooks
and equipment modification directives. These are exempted from 1320.1D
formatting provisions.

There are two kinds of user-oriented documents that apply to the
implementation of specific modification programs: modification manuals
and modification instructions. The manuals are to have similar
components to those listed in the exhibit under Maintenance Technical
Handbooks. When either of these modification program documents are
manufacturer\'s documents, they may be treated as technical issuances as
is explained later. FAA-D-2494/b, 1984 addresses instruction books for
operation and maintenance of new or modified systems and equipment. With
FAA permission, instruction books may also be technical issuances. In
such cases, writers and publishers may use other formats and
organizations. FAA-D-2494/b includes an appendix that addresses a
general evaluation of commercial instruction books.

**Definition.** **Technical Issuances**, according to FAA Order 1320.1D,
are publications acquired from non-agency sources or developed within
FAA that directly concern installation, maintenance, or modification of
equipment, equipment systems, facilities, or aircraft. Manufacturers\'
instruction books for plants and equipment are included in this
category. A basic objective of using this category is to permit the
merging of internally-developed and externally-acquired technical
manuals and publications into consolidated, single source documents.
Because of necessary deviations from standard directive format and
issuance procedures, they are designated technical issuances.

The detailed guidance of this user-interface guide represents advisable
practice to help design-in and facilitate human performance as a
component of new or changed operational systems. Its provisions may be
selectively applied to user-documentation of new and modified systems.
It may be used to help evaluate user documentation on NDI and COTS
procurements.

> []{#__RefHeading___Toc25028313 .anchor}**Exhibit 15.4** FAA directives
> and order of document components

### 15.4.1 Cover page {#cover-page .unnumbered}

-   **15.4.1.1** **Contents of cover page.** The cover page of a user
    document shall contain the explicit identifying information for the
    document including a document title, number, and date. \[Source:
    FAA-D-2494/b, 1984\]

    **Example.** An instruction book cover has the following
    elements: (a) the national stock number of the document, (b) the
    publication number, (c) a phrase specifying the type of document,
    for example User\'s Guide, (d) the name of the equipment or system
    to which the document applies, (e) if applicable, \"TYPE\" and the
    type number of the equipment or system, (f) if applicable, \"SERIAL
    NOS.\" and the range of serial numbers to which the document
    applies, (g) \"U.S. DEPARTMENT OF TRANSPORTATION,\" and (h)
    \"FEDERAL AVIATION ADMINISTRATION.\"

-   **15.4.1.2** **Type style and size, 8.5 by 11 inch (21.6 by 27.9 cm)
    pages.** The type style used on the cover page shall be bold, and it
    shall not be italic. The point size for each element for an
    instruction book is given in Exhibit 15.4.1.2. \[Source:
    FAA-D-2494/b, 1984\]

[]{#__RefHeading___Toc25028314 .anchor} **Exhibit 15.4.1.2** Type sizes
for cover page elements

> []{#__RefHeading___Toc23642057 .anchor}15.4.2 Table of contents

A table of contents serves to reveal the organization of a document as
well as to guide the user to a desired topic.

-   **15.4.2.1** **When to include a table of contents.** A user
    document shall have a table of contents unless it has fewer than
    three divisions or fewer than six pages. \[Source: FAA-D-2494/b,
    1984; Angiolillo and Roberts, 1991; Simpson and Casey, 1988\]

-   **15.4.2.2** **Labeling the table of contents.** The single word
    \"CONTENTS\" shall appear at the beginning of the table of contents.
    \[Source: MIL-STD-962B, 1988\]

-   **15.4.2.3** **What to include in the table of contents.** A table
    of contents shall include: (a) at least two levels of the headings
    and subheadings of the document, (b) appendixes if they exist, (c)
    the glossary and index if they exist, (d) lists of exhibits,
    illustrations, figures, and tables if they exist, and (e) the
    initial page number of each item listed. \[Source: FAA-D-2494/b,
    1984; MIL-STD-962B, 1988\]

-   **15.4.2.4** **Right-hand page.** The table of contents shall begin
    on a right-hand page. \[Source: FAA-D-2494/b, 1984\]

### 15.4.3 Lists of exhibits {#lists-of-exhibits .unnumbered}

Lists of exhibits (figures, tables, or any other illustrations) may
follow or may be part of the table of contents; this section contains
additional rules pertaining to lists.

**Discussion.** In this guide, exhibits which contain either or both
graphics and tabular materials are used. Such exhibits enable the user
to have the graphic and tabular data that are used together, located
together. This practice aids the user\'s task performance by eliminating
cross referencing between separate table and figure information.

-   **15.4.3.1** **Lists of exhibits.** If a document contains one or
    more instances of a type of exhibit, such as a figure or table, all
    instances shall be listed by type in the table of contents. That is,
    all figures shall be listed in a list of figures, and all tables
    shall be listed in a list of tables. \[Source: FAA-D-2494/b, 1984\]

-   **15.4.3.2** **Contents of lists of exhibits.** Lists of exhibits
    shall include: (a) the identification of the exhibit, for example,
    \"Exhibit 6-1,\" (b) the title of the exhibit, and (c) the page
    number on which the exhibit appears or begins. \[Source:
    FAA-D-2494/b, 1984\]

-   **15.4.3.3** **Location and precedence of lists.** Lists of exhibits
    shall be placed at the end of the table of contents. Each type of
    exhibit shall be listed separately, and the lists shall be placed in
    the following order: (a) exhibits labeled \"exhibit,\" (b) figures
    (or other types of illustration), (c) foldout figures, (d) tables,
    and (e) foldout tables. \[Source: Simpson and Casey, 1988\]

### 15.4.4 Figures {#figures .unnumbered}

This section contains rules for the use, identification, location,
style, content, and orientation of figures.

**Definition.** A **figure** is an exhibit that is primarily graphical
or pictorial in nature, as opposed to verbal or numerical.

#### 15.4.4.1 General

-   **15.4.4.1.1** **When to use.** Figures shall be used when they are
    likely to increase a reader\'s understanding in ways that words
    cannot. \[Source: FAA Order 1700.8D, 1992\]

-   **15.4.4.1.2** **Relationship to text.** Figures shall be clearly
    related to, consistent with, and referred to in the text of the
    document. \[Source: MIL-STD-490A, 1985; Simpson and Casey, 1988\]

#### 15.4.4.2 Identification {#identification .unnumbered}

-   **15.4.4.2.1** **Number and title.** Each figure shall have a unique
    identifying number and a title. Numbers shall be assigned
    consecutively, beginning with one, either for the document as a
    whole, or within divisions. If they are assigned within divisions,
    the division\'s identifying number shall form part of the figure\'s
    identifying number. The figure\'s title shall describe concisely
    what the figure contains. \[Source: FAA Order 1700.8D, 1992;
    FAA-D-2494/b, 1984; MIL-STD-490A, 1985; MIL-STD-962B, 1988; Simpson
    and Casey, 1988; Zaneski, 1982\]

-   **15.4.4.2.2** **Caption.** Each figure shall have a caption that
    consists of the word \"Figure\" followed by its unique identifying
    number, two spaces, and its title. The caption shall be centered
    below the figure. \[Source: FAA-D-2494/b, 1984\]

#### 15.4.4.3 Location {#location .unnumbered}

-   **15.4.4.3.1** **Preferred location.** A figure that is smaller than
    a page should be placed on the same page as its first reference,
    either within or following the paragraph that contains the
    reference. If the space following the reference is too small, the
    figure should be located at the top of the following page. A figure
    that fills a page should be placed on the page following the page
    containing its reference. \[Source: FAA Order 1700.8D, 1992;
    MIL-STD-490A, 1985; MIL-STD-962B, 1988; Simpson and Casey, 1988\]

-   **15.4.4.3.2** **Consistent location.** The location of a figure
    relative to its first reference in the text should be consistent. If
    for some reason the preferred location specified in paragraph
    15.4.4.3.2 is not satisfactory, all the figures should be grouped
    together near the end of the document. An example of this would be a
    document in which the space devoted to figures far exceeds the space
    devoted to text. \[Source: FAA Order 1700.8D, 1992; MIL-STD-490A,
    1985\]

#### 15.4.4.4 Style {#style .unnumbered}

-   **15.4.4.4.1** **Consistent style.** The figures for a document
    shall be prepared so that in their final state, that is, after any
    reduction or enlargement, they are consistent in terms of such
    characteristics as line width, shading, and style and size of type.
    \[Source: Simpson and Casey, 1988; FAA Order 1700.8D, 1992\]

```{=html}
<!-- -->
```
-   **15.4.4.4.2** **Preferred pictorial style.** Pictorial figures
    should consist of line drawings rather than photographs. \[Source:
    AFHRL-TR-73, 1973\]

    **Discussion.** While there may be circumstances in which
    photographs might be preferable, in general, line drawings have
    several advantages. In particular, they permit omission of
    distracting and irrelevant details, and they can be reproduced
    without significant loss of detail.

-   **15.4.4.4.3** **Consistent pictorial style.** All the comparable
    figures in a document should be prepared in the same style, for
    example, all line drawings, or all photographs. \[Source: Simpson
    and Casey, 1988\]

```{=html}
<!-- -->
```
-   **15.4.4.4.4** **Minimal distraction.** Decorative elements such as
    borders and background shading shall be avoided. Photographs shall
    be cropped or masked to remove irrelevant or unimportant portions
    unless those portions are helpful in orienting the reader. Photo
    masking with high reproducible quality may be an economical
    alternative to line drawings. \[Source: FAA Order 1700.8D, 1992;
    Simpson and Casey, 1988\]

-   **15.4.4.4.5** **Alphanumeric information.** All alphanumeric
    information contained in figures shall be created mechanically or
    electronically; it shall not be hand drawn. The size shall be at
    least 8 points in the figure\'s final size, that is, after any
    reduction or enlargement. \[Source: FAA-D-2494/b, 1984\]

-   **15.4.4.4.6** **Line width.** The width of lines when the figure is
    in its final size, that is, after reduction or enlargement, shall be
    at least 0.01 inch (0.25 mm). \[Source: FAA-D-2494/b, 1984\]

-   **15.4.4.4.7** **Color.** Color shall not be used in figures unless
    it is meaningful and authorized by the acquisition program office.
    \[Source: FAA Order 1700.8D, 1992\]

    **Discussion.** The use of shadings and patterns is usually as
    effective as the use of color.

#### 15.4.4.5 Content {#content .unnumbered}

-   **15.4.4.5.1** **Amount of detail.** Figures shall contain only
    necessary and useful detail, that is, they shall contain the detail
    necessary to the task being performed and additional detail that
    provides helpful context. \[Source: AFHRL-TR-73, 1973\]

-   **15.4.4.5.2** **Callouts.** Specific features of interest in a
    figure shall be identified with callouts. The text of a callout may
    be located adjacent to the feature, or the feature may be identified
    by a number, and the text located elsewhere. A callout shall consist
    of: (a) an arrow with its head pointing at the feature and its tail
    leading to a block of text or to a number, (b) a number that is
    keyed to a block of text, if applicable, and (c) a block of text
    that gives information about the feature. Numbered callouts shall be
    numbered consecutively, starting with one and beginning with the
    feature nearest \"three o\'clock\" on the figure and proceeding
    clockwise around the figure. \[Source: AFHRL-TR-73, 1973; FAA Order
    1700.8D, 1992\]

-   **15.4.4.5.3** **Specific types of diagrams.** If a document
    contains any of the following specific types of diagrams, the
    diagrams shall conform to FAA-D-2494/b, 1984: (a) block
    diagrams, (b) major function diagrams, (c) schematic diagrams, (d)
    diagrams for analog equipment, (e) diagrams for functional
    entities, (f) functional circuit diagrams, (g) photographs, (h)
    continuous-tone illustrations, (i) printed circuit board
    illustrations, (j) power distribution diagrams, (k) wiring
    diagrams, (l) cabling diagrams, (m) mechanical drawings, and (n)
    piping diagrams. For developing directives, FAA 1320.1D recommends
    that figures which are sample forms should be a filled out as an
    example to help the user. Rather than dividing form-filling
    instructions between the figure and the main text or an appendix,
    the writer should include instructions on the sample form and, where
    feasible, show variances for completion in marginal notes. \[Source:
    FAA-D-2494/b, 1984\]

####  {#section-3 .unnumbered}

#### 15.4.4.6 Orientation {#orientation .unnumbered}

-   **15.4.4.6.1** **Preferred orientation.** Figures should be oriented
    so that the reader can read them without rotating the page, that is,
    all text, including the figure\'s identification and title, should
    appear horizontally when the page is in its normal orientation.
    \[Source: FAA Order 1700.8D, 1992; MIL-STD-962B, 1988\]

```{=html}
<!-- -->
```
-   **15.4.4.6.2** **Alternate orientation.** If it is not possible to
    display a figure in the preferred orientation, it shall be oriented
    so that the top of the figure is at the left side of the page.
    \[Source: FAA Order 1700.8D, 1992; MIL-STD-962B, 1988\]

#### 15.4.4.7 Oversize figures {#oversize-figures .unnumbered}

-   **15.4.4.7.1** **Facing pages.** If a figure is too large to fit on
    a single page, if possible, it should be divided into two parts that
    are presented on facing pages. \[Source: FAA Order 1700.8D, 1992;
    MIL-STD-962B, 1988\]

```{=html}
<!-- -->
```
-   **15.4.4.7.2** **Captions for divided figures.** If a figure is
    divided and displayed on two pages, the figure\'s caption, that is,
    its identifying number and title, shall be repeated below each
    portion, with the word \"Continued\" in parentheses following the
    title. \[Source: MIL-STD-962B, 1988\]

```{=html}
<!-- -->
```
-   **15.4.4.7.3** **Foldout pages.** If a large figure cannot be
    divided and displayed on facing pages, it shall be displayed on a
    foldout page. \[Source: FAA-D-2494/b, 1984\]

### 15.4.5 Tables {#tables .unnumbered}

#### 15.4.5.1 General

-   **15.4.5.1.1** **Use.** Tables should be used: (a) when data or text
    can be displayed more clearly than can be done otherwise, or (b) to
    show large amounts of data or text more compactly than could be done
    otherwise. \[Source: FAA Order 1700.8D, 1992; MIL-STD-490A, 1985;
    MIL-STD-962B, 1988; FAA-D-2494/b, 1984\]

    **Definition.** A **table** is an array of data or text in rows and
    columns. Usually at least one dimension, either the rows or the
    columns, is labeled; sometimes both are labeled.

    **Examples.** Some examples of information that might be presented
    in tables are: (a) performance standards and operating
    tolerances, (b) functions of controls and indicators, (c) operating
    parameters, (d) turn-on and checkout procedures, (e) performance
    checks, and (f) procedures for preventive and corrective
    maintenance, alignment, and calibration.

#### 15.4.5.2 Identification {#identification-1 .unnumbered}

-   **15.4.5.2.1** **Number and title.** Each table shall have a unique
    identifying number and title. Numbers shall be assigned
    consecutively, beginning with one, either for the document as a
    whole, or within divisions. If they are assigned within divisions,
    the division\'s identifying number shall form part of the table\'s
    identifying number, for example, \"Table 2-1\" would indicate the
    first table in division two. The table\'s title shall describe
    concisely what the table contains. \[Source: FAA-D-2494/b, 1984; FAA
    Order 1700.8D, 1992; MIL-STD-490A, 1985; MIL-STD-962B, 1988\]

-   **15.4.5.2.2** **Caption.** Each table shall have a caption that
    consists of the word \"Table\" followed by its unique identifying
    number, two spaces, and a title. The caption shall be centered above
    the table. \[Source: FAA-D-2494/b, 1984\]

#### 15.4.5.3 Location {#location-1 .unnumbered}

-   **15.4.5.3.1** **Preferred location.** A table should be placed on
    the same page as its reference, either within or following the
    paragraph that contains the reference. If the space following the
    reference is too small, the table should be located at the top of
    the following page. A table that fills a page should be placed on
    the page following the page containing its reference. \[Source: FAA
    Order 1700.8D, 1992\]

-   **15.4.5.3.2** **Consistent location.** The relative location of a
    table to its first reference in the text should be consistent. If
    for some reason the preferred location specified in paragraph
    15.4.5.3.2 is not satisfactory, all the tables should be grouped
    together near the end of the document. An example of this would be a
    document in which the space devoted to tables far exceeds the space
    devoted to text. \[Source: FAA Order 1700.8D, 1992; MIL-STD-490A,
    1985\]

#### 15.4.5.4 Formatting {#formatting .unnumbered}

-   **15.4.5.4.1** **Organization.** Tables shall be organized to show
    the significance and relationships in their contents as clearly and
    simply as possible. \[Source: FAA Order 1700.8D, 1992; MIL-STD-490A,
    1985\]

-   **15.4.5.4.2** **Type size.** The size of type used within a table
    shall be at least 8 points when the table is in its final form, that
    is, after any reduction or enlargement. \[Source: FAA Order 1700.8D,
    1992; FAA-D-2494/b, 1984\]

-   **15.4.5.4.3** **Units of measurement.** If the entries in a row or
    column consist of some sort of quantity, the unit of measurement,
    such as inches or degrees, shall be given in the row or column
    label; it shall not be repeated after each quantity. \[Source: FAA
    Order 1700.8D, 1992\]

-   **15.4.5.4.4** **Ease of reading.** It shall be easy for the reader
    to follow rows and columns visually. \[Source: FAA-D-2494/b, 1984,
    3.1.7.3; Simpson and Casey, 1988\]

    **Discussion.** There are three common ways to help readers follow
    rows and columns: (a) the use of white space, for example, a blank
    line after every four or a maximum of five rows and generous spacing
    between columns, (b) the use of vertical and horizontal lines,
    and (c) the shading of alternate rows or columns. Contemporary
    practice is to use white space and shading rather than vertical and
    horizontal lines.

#### 15.4.5.5 Content {#content-1 .unnumbered}

-   **15.4.5.5.1** **Useful and relevant.** The information presented in
    a table shall be limited to information that is likely to be used by
    a reader. Tables shall contain only information that is relevant to
    the associated text. \[Source: FAA-D-2494/b, 1984; MIL-STD-490A,
    1985; MIL-STD-962B, 1988\]

-   **15.4.5.5.2** **Non-redundant information.** Tables and text shall
    not be redundant; that is, tables shall not simply restate
    information that is presented in the text. \[Source: MIL-STD-490A,
    1985; MIL-STD-962B, 1988\]

    **Discussion.** This rule is not intended to prohibit text from
    quoting, summarizing, or commenting upon the information in a table.
    In general, the purpose of the associated text is to make the
    purpose of the table clear, and the purpose of the table is to
    present data relevant to the associated text.

#### 15.4.5.6 Orientation {#orientation-1 .unnumbered}

-   **15.4.5.6.1** **Preferred orientation.** Tables should be oriented
    so that the reader can read them without rotating the page, that is,
    all text, including the table\'s identification and title and any
    row and column labels, should appear horizontally when the page is
    in its normal orientation. \[Source: FAA Order 1700.8D, 1992\]

```{=html}
<!-- -->
```
-   **15.4.5.6.2** **Alternate orientation.** If it is not possible to
    display a table in the preferred orientation, it shall be oriented
    so that the top of the table is at the left side of the page.
    \[Source: FAA Order 1700.8D, 1992; MIL-STD-490A, 1985; MIL-STD-962B,
    1988\]

#### 15.4.5.7 Oversize tables {#oversize-tables .unnumbered}

-   **15.4.5.7.1** **Facing pages.** If a table is too large to fit on a
    single page, if possible, it should be divided into two parts that
    are presented on facing pages. \[Source: FAA Order 1700.8D, 1992;
    MIL-STD-962B, 1988\]

```{=html}
<!-- -->
```
-   **15.4.5.7.2** **Captions for divided tables.** If a table is
    divided and displayed on two pages, the table\'s caption, that is,
    its identifying number and title shall be repeated above each
    portion, followed by the word \"Continued\" in parentheses.
    \[Source: MIL-STD-962B, 1988\]

-   **15.4.5.7.3** **Foldout pages.** If a large table cannot be divided
    and displayed on facing pages, it shall be displayed on a foldout
    page. \[Source: FAA-D-2494/b, 1984\]

### 15.4.6 Lists {#lists .unnumbered}

It is often convenient to present information in the form of a list.

**Definition.** As used in this section, a **list** is a series of
similar or related items in which each item is marked and displayed on a
separate line or lines. The markings can be graphic symbols, such as
bullets () or squares (), or sequential identifiers, such as numbers
or letters. An item can be a word, a phrase, a sentence, or a group of
sentences.

-   **15.4.6.1** **Marks.** If the items in a list have no precedence
    over each other and there is no need to refer to them individually,
    they should be marked with graphic symbols, such as bullets. If the
    items do have precedence, for example, if they are sequential steps
    in a procedure, or if they need to be referred to individually, they
    should be marked with numbers or letters. \[Source: Rubens, 1992\]

-   **15.4.6.2** **Punctuation items.** If an item consists of one or
    more complete sentences, it should be followed by a period. If an
    item is not a complete sentence, it should be followed by a comma,
    with two exceptions: (a) the next to last item should be followed by
    a comma and either the word \"and\" or \"or,\" and (b) the last item
    should be followed by a period. \[Source: Rubens, 1992\]

### 15.4.7 Formulas and equations {#formulas-and-equations .unnumbered}

-   **15.4.7.1** **Identification.** Formulas and equations that occur
    in user documents shall be numbered consecutively, in Arabic
    numerals, beginning with one. The number shall appear in parentheses
    at the right margin on the last line of the formula or equation.
    \[Source: FAA Order 1700.8D, 1992\]

```{=html}
<!-- -->
```
-   **15.4.7.2** **Location.** Short formulas and equations that are not
    part of a series should be placed in the text rather than displayed
    on a separate line. Formulas and equations that are longer or that
    are part of a series shall be displayed either indented or centered
    in a line immediately below the text that refers to them. A group of
    separate but related formulas or equations should be aligned on
    their equal signs, and the group as a whole should be indented or
    centered on the page. \[Source: FAA Order 1700.8D, 1992\]

```{=html}
<!-- -->
```
-   **15.4.7.3** **Format.** If a formula or equation includes a
    numerator and denominator, they shall be separated by a line equal
    to the length of the longer term; both terms shall be centered with
    respect to the line. \[Source: FAA Order 1700.8D\]

### 15.4.8 Warnings, cautions, and notes {#warnings-cautions-and-notes .unnumbered}

This section contains criteria governing the use of warnings, cautions,
and notes.

**Definitions.** A **warning** is a written notice given to a reader
when a situation might result in personal injury or loss of life; a
**caution** is a written notice given when a situation might result in
damage to or destruction of equipment or systems; a **note** a written
notice given to draw the reader\'s attention to something or to supply
additional information.

-   **15.4.8.1** **When to use.** Warnings shall be provided whenever a
    step or procedure or the failure to perform a step or procedure
    correctly might result in personal injury to, or loss of life of,
    the user or anyone else. Cautions shall be provided whenever a step
    or procedure or the failure to perform a step or procedure correctly
    might result in damage or destruction of equipment or systems. Notes
    shall be provided whenever it seems appropriate to call the
    reader\'s attention to something or to provide additional
    information. \[Source: FAA-D-2494/b, 1984\]

-   **15.4.8.2** **Warnings.** Warnings shall consist of (a) the word
    \"WARNING\" in upper case letters, enclosed in a border, and
    centered on the page, and (b) the text of the warning, indented from
    both margins and centered on the page. The text of the warning shall
    include (a) a brief description of the hazard, (b) the likely result
    if the warning is ignored, and (c) specific steps to take to avoid
    the hazard. Warnings shall precede the information to which they
    apply. \[Source: FAA-D-2494/b, 1984; MIL-M-87268, 1995\]

-   **15.4.8.3** **Cautions.** Cautions shall consist of (a) the word
    \"CAUTION\" in upper case letters and centered on the page, and (b)
    the text of the caution, indented from both margins and centered on
    the page. The text of a caution shall include (a) a brief
    description of the hazard, (b) the likely result if the hazard is
    ignored, and (c) specific steps to take to avoid the hazard.
    Cautions shall precede the information to which they apply.
    \[Source: FAA-D-2494/b, 1984; MIL-M-87268, 1995\]

-   **15.4.8.4** **Notes.** Notes shall consist of (a) the word \"NOTE\"
    in upper case letters and centered on the page, and (b) the text of
    the note, indented from both margins and centered on the page. The
    text of a note shall include the information that is to be given to
    the reader. Notes shall either immediately precede or immediately
    follow the information to which they apply, depending upon the
    content of the note and the text to which it applies. \[Source:
    FAA-D-2494/b, 1984; MIL-M-87268, 1995\]

-   **15.4.8.5** **Precedence of warnings, cautions, and notes.** If
    more than one type of notice applies at the same place in a
    document, for example, if a hazard exists to both people and
    equipment, the order in which the notices appear shall be warnings,
    cautions, and notes. \[Source: FAA-D-2494/b, 1984; MIL-M-87268,
    1995\]

-   **15.4.8.6** **No procedural steps.** Warnings, cautions, and notes
    shall not contain procedural steps. \[Source: FAA-D-2494/b, 1984;
    MIL-M-87268, 1995\]

### 15.4.9 Appendixes {#appendixes .unnumbered}

This section contains rules for appendixes.

**Definition.** An **appendix** is a body of supplementary information
collected, labeled, and placed at the end of a document.

-   **15.4.9.1** **When to use.** Information that supplements, but is
    not integral to, the main body of a document should be placed in one
    or more appendixes. Examples of such information include
    illustrations, applications, calculations, and formulas. Appendixes
    should be used only if the information is essential. \[Source: FAA
    Order 1700.8D, 1992\]

```{=html}
<!-- -->
```
-   **15.4.9.2** **Relation to main body.** The content of an appendix
    shall be within the scope of the document and shall not be
    inconsistent with the document itself. An appendix shall be referred
    to in the main body of the document. \[Source: FAA Order 1700.8D,
    1992; MIL-STD-962B, 1988\]

-   **15.4.9.3** **Identification.** Each appendix in a document should
    have an identifying letter and a title. Identifying letters shall be
    assigned consecutively, beginning with \"A.\" The title shall be
    brief but descriptive. \[Source: FAA Order 1700.8D, 1992;
    MIL-STD-962B, 1988\]

    **Discussion.** FAA Order 1320.1D requires that appendixes of
    directives be identified by an Arabic numeral designator with pages
    numbered within each appendix (for example 1- page 1, 1- page 2 and
    so on). FAA-D-2494/b, 1984 for instruction books uses Roman numerals
    for appendix designators. The present guidance document recommends
    alphabetic designator for appendixes and page numbering within each
    appendix (for example, A-1, A-2, \... B-1, B-2, and so forth). This
    designation helps the users of reference type documents to
    distinguish between main chapters and appendixes and aids them in
    navigating through the document.

-   **15.4.9.4** **Page numbering.** Each page of an appendix shall have
    a number that consists of the letter that identifies the appendix
    followed by a dash followed by the number of the page within the
    appendix. For example, B-2 would indicate the second page of
    Appendix B. Page numbers shall be located in the same relative
    position on the page as page numbers in the main body of the
    document. \[Source: FAA Order 1700.8D, 1992\]

-   **15.4.9.5** **Pagination.** Each appendix shall begin on a
    right-hand (odd-numbered) page. Appendixes shall not have title
    pages; rather, the title shall appear at the top of the first page
    of the appendix. \[Source: FAA Order 1700.8D, 1992\]

### 15.4.10 Glossary {#glossary .unnumbered}

-   **15.4.10.1** **Terms.** Special terms and words used in technical
    or unusual ways shall be defined where they first appear in the
    text. If there are many such terms, they shall also be collected in
    a glossary located near the end of the document. \[Source: FAA Order
    1700.8D, 1992\]

-   **15.4.10.2** **Format.** The glossary shall consist of (a) an
    alphabetic listing of all the special or unusual terms that appear
    in the document, and (b) their definitions. The definitions shall be
    the same as those that appear in the text where the terms are first
    defined. \[Source: Zaneski, 1982\]

### 15.4.11 Index {#index .unnumbered}

An index can greatly enhance the usability of a document, increasing
both the speed and the likelihood of a user\'s finding the desired
information.

-   **15.4.11.1** **When to use.** Documents that are lengthy or complex
    shall have indexes. \[Source: FAA Order 1700.8D, 1992\]

-   **15.4.11.2** **Format and content.** An index shall consist of an
    alphabetic listing of the terms and topics that exist in the
    document and the pages on which they can be found. Each alphabetic
    group shall be preceded by the initial letter of the group. This
    letter shall appear in upper case type that is larger and bolder
    than the entries. \[Source: FAA Order 1700.8D, 1992; Zaneski, 1982\]

```{=html}
<!-- -->
```
-   **15.4.11.3** **Level of detail.** An index should contain more
    levels of detail than does a table of contents. \[Source: Simpson
    and Casey, 1988\]

```{=html}
<!-- -->
```
-   **15.4.11.4** **Location.** An index shall be the last division of a
    document. \[Source: MIL-STD-962B, 1988\]

### 15.4.12 User feedback forms {#user-feedback-forms .unnumbered}

-   **15.4.12.1** **When to use.** All user guides and manuals shall
    include forms inviting feedback from users. \[Source: FAA-D-2494/b,
    1984\]

-   **15.4.12.2** **Location.** User feedback forms shall be the very
    last pages in the document, that is, they shall be bound just before
    the back cover. \[Source: FAA-D-2494/b, 1984\]

-   **15.4.12.3** **Content.** The form shall solicit from users of the
    document at least those categories of information illustrated in
    Exhibit 15.4.12.3 (a). The fields for the document identifier and
    title shall be printed on the form, that is, the user shall not have
    to write them in. The form shall be self-addressed and shall have an
    \"Official Business\" postage permit, as illustrated in Exhibit
    15.4.12.3 (b). Appendix 15 of FAA Order 1320.1D shows a sample
    feedback form for users of formal directives. This form encourages
    users to suggest subject matter for future additions. \[Source:
    FAA-D-2494/b, 1984; MIL-STD-962B, 1988\]

    []{#__RefHeading___Toc25028315 .anchor}**Exhibit 15.4.12.3 (a)**
    User Feedback form -- Front

    ![](media/image3.wmf)

    []{#__RefHeading___Toc25028316 .anchor}**Exhibit 15.4.12.3 (b)**
    User feedback form - Back

    ![](media/image4.wmf)

-   **15.4.12.4** **Number of copies.** Three copies of the user
    feedback form shall be bound with the document. \[Source:
    FAA-D-2494/b, 1984\]

### 15.4.13 Tabs {#tabs .unnumbered}

-   **15.4.13.1** **When to use.** Tabs should be provided if a document
    has many divisions. If a document has tabs, it should have a tab for
    each major division, for each frequently-used division, or both.
    \[Source: Simpson and Casey, 1988\]

**Discussion.** Some sort of balance is needed between the number of
tabs in a document and the number of pages between tabs. If there are a
few long divisions, tabs might be used within divisions; on the other
hand, if there are many short divisions, one tab might serve several
divisions. A rule of thumb might be that three or four tabs is so few
that they would not be helpful and that more than 20 or 30 tabs might be
so many that they would interfere rather than help.

### 15.4.14 Footnotes {#footnotes .unnumbered}

Footnotes, like appendixes, are used to present information that is not
properly a part of the text. The difference is that footnotes tend to be
much shorter and more closely related to the specific text than are
appendixes.

-   **15.4.14.1** **Minimize use of footnotes.** The use of footnotes
    shall be minimized. \[Source: MIL-STD-490A, 1985, 3.2.11.1;
    MIL-STD-962B, 1988; Hartley, 1978\]

    **Discussion.** Footnotes may be distracting and often are ignored.
    If the information is important, it properly belongs in the text; if
    the information is not important, it is probably not necessary.
    Extensive supplemental information belongs in an appendix.

-   **15.4.14.2 Identification.** Footnotes to text shall be numbered
    consecutively throughout a document or throughout a division of a
    document. The reference to a footnote in the text shall consist of
    the footnote\'s number in superscript Arabic numerals immediately
    following the word or phrase to which it applies. The footnote
    itself shall be preceded by its identifying number, also in
    superscript. Footnotes to figures or tables shall be numbered
    consecutively or otherwise identified (see the following Exception)
    independently for each figure or table. \[Source: MIL-STD-962B,
    1988\]

    **Exception.** If footnotes occur in tables or figures, and the use
    of numbers to identify them might lead to confusion with numerical
    data in the table or figure, letters and symbols are acceptable
    alternatives for identifying footnotes.

-   **15.4.14.3** **Location.** Footnotes to text shall be located at
    the bottom of the page on which their reference in the text occurs.
    Footnotes to figures or tables shall be located immediately
    following the figure or table. \[Source: MIL-STD-490A, 1985;
    MIL-STD-962B, 1988\]

### 15.4.15 Copyright and patent issues {#copyright-and-patent-issues .unnumbered}

-   **15.4.15.1** **Copyrighted documents.** If a user document is or
    will be copyrighted, the copyright information shall be placed on
    the back of the title page. \[Source: Zaneski, 1982\]

-   **15.4.15.2** **Inclusion of copyrighted or patented material.**
    Copyrighted or patented material shall not be included in user
    documents without the prior consent of the owner of the copyright or
    patent. When such consent has been obtained, and if the owner
    requests it, an acknowledgment of the permission shall be placed in
    the document near the material. \[Source: MIL-STD-962B, 1988\]

### 15.4.16 Publication date {#publication-date .unnumbered}

-   **15.4.16.1** **Location.** The date of publication shall appear at
    the center of the bottom of the front cover. \[Source: FAA-D-2494/b,
    1984\]

## 15.5 Specific user document contents {#specific-user-document-contents .unnumbered}

This section contains rules for two specific types of user document
contents, proceduralized instructions and interactive electronic
technical manuals.

### 15.5.1 Proceduralized instructions {#proceduralized-instructions .unnumbered}

Proceduralized instructions tell users how to complete tasks. They may
be used for (a) mechanical procedures, such as assembling, servicing,
and repairing units of equipment, (b) operating procedures, such as
starting, operating, and shutting down systems or units of equipment,
and (c) test procedures, such as periodic maintenance tests and
alignments. The instructions are presented as a series of steps.

**Definition.** A **proceduralized instruction** is a set of
step-by-step instructions a procedure intended to ensure the successful
completion of a task.

#### 15.5.1.1 General

-   **15.5.1.1.1 Procedures, tasks, subtasks, and steps.** A
    proceduralized instruction shall apply to a single task and shall
    present instructional information as a series of steps. A lengthy or
    complicated procedure may be divided into a series of related
    subtasks as long as each subtask accomplishes a distinct,
    recognizable objective. \[Source: Department of Defense
    (MIL-M-87268, 1995\]

-   **15.5.1.1.2** **Level of detail.** Proceduralized instructions
    shall include a level of detail that is appropriate to the intended
    users. \[Source: Wieringa, Moore, & Barnes, 1993\]

-   **15.5.1.1.3** **Completeness.** Each proceduralized instruction
    shall contain all the steps and supporting information required to
    successfully complete the task. \[Source: AFSC DH 1-3, 1980;
    MIL-HDBK-761A, 1989\]

-   **15.5.1.1.4** **Safety considerations.** The performance of all
    procedures shall be made as safe as possible by including all of the
    following safeguards that apply:

a.  If possible, actions shall be performed with equipment shut down and
    isolated.

b.  At the completion of a task or subtask, no portion of a unit of
    equipment shall be left in a dangerous state unless the procedure
    includes the posting of adequate warnings.

c.  Steps that tell a user to remove voltage or pressure shall also tell
    the user to label or tag the switches, circuits, or valves involved.

d.  If components capable of holding a charge are involved, the
    procedure shall tell the user how to discharge these components
    safely.

e.  Procedures shall include steps to restore equipment to a safe
    operating condition.

f.  Procedures shall include warnings, cautions, and notes as
    appropriate. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.1.1.5** **General safety instructions.** A proceduralized
    instruction shall include a summary of any general safety
    information that applies throughout the task. \[Source:
    MIL-HDBK-761A, 1989\]

#### 15.5.1.2 Organization and content {#organization-and-content .unnumbered}

-   **15.5.1.2.1** **Hierarchical, logical, and consistent.** A
    proceduralized instruction shall be organized in a hierarchical,
    logical, consistent manner that is apparent to the user. \[Source:
    Wieringa, Moore, & Barnes, 1993\]

-   **15.5.1.2.2** **Identifying information.** Information identifying
    the procedure shall be displayed on the cover page of the procedure
    and in a header or footer on each page. \[Source: Wieringa, Moore, &
    Barnes, 1993\]

-   **15.5.1.2.3** **Title.** A proceduralized instruction shall have a
    title that is concrete, specific, and terse, and that uniquely
    identifies the task to be performed. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.1.2.4** **Headings.** If a proceduralized instruction
    contains distinct parts, each part shall have a heading. Headings
    shall conform to the requirements for titles (see paragraph
    15.2.1.1.1). \[Source: Wieringa, Moore, & Barnes, 1993\]

-   **15.5.1.2.5** **Numbered steps.** Steps shall be numbered, using
    Arabic numerals, in a way that provides useful information to users
    without being overly complex. \[Source: MIL-HDBK-761A, 1989;
    Wieringa, Moore, & Barnes, 1993\]

    **Discussion.** A complex step might be divided into a number of
    substeps, and the numbering might reflect this. For example, if step
    6 has three substeps, the substeps might be numbered 6.1, 6.2, and
    6.3.

-   **15.5.1.2.6** **Supporting information.** A proceduralized
    instruction shall include all of the following supporting
    information that is applicable:

a.  An applicability statement that specifies the equipment or systems
    to which the procedure applies (for example, the applicability
    statement might list equipment model numbers and a range of serial
    numbers);

b.  Any initial setup or input conditions required for the procedure;

c.  A list of test equipment required;

d.  A list of tools required;

e.  A list of materials, consumable or expendable items, and mandatory
    replacement parts required;

f.  A list of support equipment required;

g.  If more than one, the minimum number of personnel required;

h.  A system preparation checklist; and,

i.  A list of any special environmental conditions required (for
    example, ventilation, lighting, temperature, noise level,
    electromagnetic interference, cleanliness, and humidity). \[Source:
    MIL-HDBK-761A, 1989\]

-   **15.5.1.2.7** **Appendixes and attachments.** Information that is
    important and useful but not easily incorporated into a procedure
    should be presented in an appendix or attachment to the procedure.
    However, the use of appendixes and attachments should be minimized.
    \[Source: Wieringa, Moore, & Barnes, 1993\]

    **Examples.** Types of information presented in appendixes or
    attachments might include contingency actions, actions performed by
    someone other than the user of the procedure, and periodic steps.

#### 15.5.1.3 Format {#format .unnumbered}

-   **15.5.1.3.1** **Step numbers and text.** The text of a step shall
    begin on the same line as its number, separated from the number by
    two spaces. If the text fills more than one line, the additional
    line or lines shall begin under the first letter of the first line,
    not under the number. \[Source: Department of Defense (MIL-M-38784,
    1992\]

```{=html}
<!-- -->
```
-   **15.5.1.3.2** **Check off provision.** If appropriate, the
    proceduralized instruction should provide a line or box adjacent to
    a step so that a user can check off the step when it has been
    completed. \[Source: Wieringa, Moore, & Barnes, 1993\]

    **Discussion.** The provision of a check off can serve a variety of
    functions; it can serve as a placeholder in cases in which a user
    refers to another part of the procedure or another procedure; it can
    serve as a record of the completion of the step; and it can be used
    to identify the applicable condition in a conditional step.

-   **15.5.1.3.3** **Lists.** If a step contains a sequence of three or
    more items (for example, actions, conditions, or units of
    equipment), the items should be presented in a list format (see
    section 15.4.6). \[Source: Wieringa, Moore, & Barnes, 1993\]

```{=html}
<!-- -->
```
-   **15.5.1.3.4** **Illustrations.** If a step refers to an
    illustration, it shall be possible for the user to see both the step
    and the illustration simultaneously. This may be accomplished by
    placing the illustration (a) within the step in which it is
    used, (b) on the same page as the step, (c) on a facing page, or (d)
    on a foldout page (see section 15.3.2.7). \[Source: AFSC DH 1-3,
    1980\]

#### 15.5.1.4 Wording of steps {#wording-of-steps .unnumbered}

-   **15.5.1.4.1** **Completeness.** Each step shall contain all the
    instructions and supporting information required to successfully
    complete the step. \[Source: AFSC DH 1-3, 1980\]

-   **15.5.1.4.2** **Grammar.** The steps in a proceduralized
    instruction shall be comprised of grammatically correct sentences.
    \[Source: Wieringa, Moore, & Barnes, 1993\]

-   **15.5.1.4.3** **Action statements and indication statements.** If
    appropriate, a step in a proceduralized instruction shall be
    comprised of an action statement followed by an indication
    statement. The indication statement shall include any applicable
    values or tolerances. \[Source: MIL-HDBK-761A, 1989\]

    **Definitions.** An **action statement** is an action verb followed
    by the object or item acted upon. An **indication statement** states
    the name of an indicator that the user reads or observes and the
    indication expected to result from the action. The **stated
    indication** is what is expected if the equipment or system is
    operating normally.

-   **15.5.1.4.4** **Standard steps.** If the same (or highly similar)
    action or indication occurs more than once in a procedure, a
    standard wording shall be adopted and used consistently throughout
    the procedure. Such standard wording shall, as appropriate,
    accommodate different objects and indicators. \[Source:
    MIL-HDBK-761A, 1989\]

-   **15.5.1.4.5** **Conditional steps.** Steps that are to be performed
    only if a specified condition exists shall begin with the word
    \"if\" or \"when\" and a statement of the condition, followed by the
    word \"then\" and the action statement. If and then shall be
    emphasized typographically (see section 15.3.3.7). If the condition
    is negative, the word not shall be used and emphasized. \[Source:
    Wieringa, Moore, & Barnes, 1993\]

    **Examples.** Examples of conditional steps are: \"If the status
    light is green, then press the override button,\" \"When engine
    speed reaches 2000 RPM, then engage the clutch,\" and \"If the
    status light is not green, then press the power switch.\"

-   **15.5.1.4.6** **No calculations.** If possible, no step shall
    require a user to make a calculation. If a calculation is necessary,
    the step shall include a calculation aid, for example, a series of
    step-by-step instructions for carrying out the calculation.
    \[Source: Wieringa, Moore, & Barnes, 1993\]

```{=html}
<!-- -->
```
-   **15.5.1.4.7** **Numerical precision.** If a step contains numerical
    information that relates to an indicator, the precision of the
    information in the step should not exceed the precision of the
    indicator. For example, if an instrument dial can be read only to
    the nearest five units, the step should not require a reading to the
    nearest single unit. \[Source: Wieringa, Moore, & Barnes, 1993\]

```{=html}
<!-- -->
```
-   **15.5.1.4.8** **Numerical ranges.** If a step specifies a range of
    numerical values, the range shall be stated as the upper and lower
    values, not as the middle value plus and minus an increment. For
    example, a temperature range might be stated as 75-85°F, not as 80°F
    ±5°. \[Source: Wieringa, Moore, & Barnes, 1993\]

#### 15.5.1.5 Branching and cross-references {#branching-and-cross-references .unnumbered}

Not every procedure is a simple, sequential series of steps. Some
require branching depending upon conditions (for example, \"If the
condition is *A*, then go to step *X*; if the condition is *B*, then go
to step *Y*\"), and some require a temporary reference to another step
or procedure followed by a return to the current procedure (for example,
\"If the condition observed in step *N* is *C*, then perform procedure
*Z* before performing step *N+1*\").

-   **15.5.1.5.1** **Minimize use.** The use of branching and
    cross-referencing in proceduralized instructions shall be minimized.
    \[Source: Wieringa, Moore, & Barnes, 1993\]

-   **15.5.1.5.2** **Explicit instructions.** Branching and
    cross-referencing shall be explicit, not implicit. \[Source:
    Wieringa, Moore, & Barnes, 1993\]

-   **15.5.1.5.3** **Content.** Branching and cross-referencing
    instructions shall provide all necessary information and shall be
    worded consistently. \[Source: Wieringa, Moore, & Barnes, 1993\]

    **Examples.** Branching instructions might be worded: \"If \...,
    then go to step \...\" A cross-referencing instruction might be
    worded: \"Refer to steps \... then return to step \...\"

#### 15.5.1.6 Miscellaneous {#miscellaneous .unnumbered}

-   **15.5.1.6.1** **Simultaneous actions or indications.** If a
    procedure includes actions that must occur simultaneously or
    indications that occur simultaneously, the actions or indications
    shall be included in the same step. \[Source: MIL-HDBK-761A, 1989\]

```{=html}
<!-- -->
```
-   **15.5.1.6.2** **Format for diagnostic steps.** The format of a
    diagnostic step should be appropriate to the immediate task.
    \[Source: Wieringa, Moore, & Barnes, 1993\]

-   **15.5.1.6.3** **Nonsequential steps.** Steps that need not be
    performed in a fixed sequence should be presented in a way that
    makes clear when they should be performed and that ensures they are
    not omitted. \[Source: Wieringa, Moore, & Barnes, 1993\]

    **Discussion.** In some cases, a number of steps must be performed,
    but the order in which they are performed does not matter. In
    others, a step must be performed when a condition is met, for
    example, shutting a valve when a tank becomes full. In still others,
    a step must be performed at specified intervals or at a specified
    time after an action has been taken.

-   **15.5.1.6.4** **Verification steps.** Steps that require a user to
    verify that a stated condition is met should be presented in an
    appropriate format, for example, with a check box. If a procedure
    contains more than one verification step, the verification steps
    should have a consistent format. \[Source: Wieringa, Moore, &
    Barnes, 1993\]

-   **15.5.1.6.5** **Equally-acceptable steps.** Steps that tell a user
    to perform one of a number of equally acceptable actions should be
    presented in a format that makes clear exactly what the user is to
    do, for example, to select and perform one and only one action.
    \[Source: Wieringa, Moore, & Barnes, 1993\]

```{=html}
<!-- -->
```
-   **15.5.1.6.6** **Actions performed from memory.** If a procedure
    includes one or more steps that a user is expected to perform from
    memory, the written procedure shall include those steps. \[Source:
    Wieringa, Moore, & Barnes, 1993\]

    **Example.** The first step(s) in an emergency procedure may have to
    be done from memory. Whenever the total procedure is written out,
    the memorization steps are assumed to be necessary and are included.

-   **15.5.1.6.7** **Procedures involving more than one person.** A
    procedure that involves more than one person shall be presented in a
    way that assigns actions and observations to individuals and
    integrates the actions and observations of all the individuals into
    a single series of steps. \[Source: MIL-HDBK-761A, 1989\]

### 15.5.2 Interactive electronic technical manuals {#interactive-electronic-technical-manuals .unnumbered}

Interactive electronic technical manuals are technical manuals designed
for interactive use on an electronic display system. This medium has
many advantages, such as (a) tailoring the presentation to the user, for
example, presenting highly detailed information to novice users and
condensed information to experienced users, (b) tailoring the
presentation to the situation, for example, following one branch rather
than another based on a user input, (c) permitting the manipulation
(such as movement or enlargement) of diagrams, and (d) permitting easy
access to information, such as parts information.

#### 15.5.2.1 General

-   **15.5.2.1.1** **Access to contents.** A user shall be able to
    access directly any portion of the manual that appears in a list of
    its contents. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.1.2** **Help information.** The system shall provide at the
    user\'s request additional information relating to the technical
    content of all sections of the electronic technical manual. This
    help shall include both context-sensitive help applicable to the
    user\'s current activity and situation, and descriptive information
    on a specific term, technical point, or process. Help information
    shall include:

a.  administrative information about the manual itself, for example, the
    title and identification, the version number, the date of the latest
    change, and the preparing organization;

b.  an easily noticeable applicability statement that specifies
    precisely the equipment or system to which the manual applies,
    including model numbers and serial numbers, if applicable;

c.  an introduction that states the purpose, scope, contents,
    organization, and range of tasks covered by the manual;

d.  information on how to use the help information;

e.  information about the computer system being used to view the manual;

f.  instructions on the use of any utility functions provided, for
    example, the automatic preparation and submission of reports;

g.  information about function keys and other keyboard features;

h.  general information about the task being performed or the portion of
    the manual being used;

i.  specific, context-sensitive help;

j.  an index of help information; and,

k.  definitions of abbreviations and unusual terms. \[Source:
    MIL-HDBK-761A, 1989\]

**Discussion.** The above rule does not imply that an electronic
technical manual or a help subsystem can merely be a paper manual
transposed to a help role by its presentation or availability through a
computer system monitor. To the contrary, such a practice may produce a
nearly useless help system or electronic technical manual. Help systems
and electronic technical manuals need to be designed along with the
system, especially along with software systems.

Such systems and electronic manuals need to be based upon human
understanding of technical information related to human tasks,
processes, interfaces, and other subsystem that they use and maintain to
enable their individual and collective purposeful endeavors. Using
computer technology to turn pages is a questionable practice. Hypertext
help is much more appropriate than a paper manual transposed to be a
help system.

-   **15.5.2.1.3** **Safety summary.** If an interactive electronic
    technical manual contains one or more warnings or cautions, it shall
    also include a safety summary. \[Source: MIL-HDBK-761A, 1989\]

#### 15.5.2.2 Text {#text .unnumbered}

-   **15.5.2.2.1** **Applicable information.** The system shall present
    to users only information that applies to the specific equipment or
    system configuration and situation. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.2.2** **Level of detail.** An interactive electronic
    technical manual shall contain all the information necessary for a
    user (a) to perform the task involved without error or loss of time
    due to insufficient information, or (b) to comprehend a description.
    It shall not contain unnecessary detail. \[Source: MIL-HDBK-761A,
    1989\]

-   **15.5.2.2.3** **Procedures in steps.** If a step includes a
    procedure that is specific to the equipment or system, the procedure
    shall be included in the step. If a step includes a general-purpose
    procedure that is likely to be performed without reference to
    technical information by an experienced technician, the user shall
    be given the option of bypassing presentation of the procedure.
    \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.2.4** **Accommodating novice and expert skill levels.** If
    specified by the acquisition program office, an interactive
    electronic technical manual shall offer two levels of detail, one
    for a novice skill level, and one for an expert skill level. The
    novice skill level shall contain all information necessary for an
    inexperienced user to perform the task involved or to comprehend a
    description. The expert level shall function as a checklist,
    presenting only the steps required to complete a task or providing a
    description in broader terms, requiring a higher level of
    theoretical knowledge. Both levels shall contain all pertinent
    warnings and cautions. The expert user shall be able to access
    information at the novice level, but the novice user shall not be
    able to access information at the expert level unless otherwise
    specified by the acquisition program office. \[Source:
    MIL-HDBK-761A, 1989\]

#### 15.5.2.3 Graphics {#graphics .unnumbered}

The types of graphic displays that might appear in an interactive
electronic technical manual include, but are not limited to, locator
diagrams, functional block diagrams, general support graphics,
schematics, wiring diagrams, flow diagrams, graphs, and charts.

-   **15.5.2.3.1** **Minimum quality.** Graphic displays shall meet the
    general requirements of paragraph 15.5.2.3.1 when displayed on the
    least capable device (for example, the smallest screen) on which the
    manual is intended to be used. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.3.2** **Interaction with graphics.** A displayable graphic
    may or may not be designed to be used interactively. If a graphic is
    not interactive, it shall be displayed in full detail; if it is
    interactive, a user shall be able to (a) manipulate the graphic for
    a better view, for example, by moving or re-sizing it, (b) choose
    selectable areas within the graphic, or (c) both. \[Source:
    MIL-HDBK-761A, 1989\]

    **Discussion.** An interactive graphic would be appropriate if the
    graphic is so large or detailed that it cannot be displayed in full
    detail in the space available, and thus requires the use of
    scrolling or zooming.

-   **15.5.2.3.3** **Detail and context.** Graphics shall present only
    the equipment items to which action statements refer and enough of
    their surroundings to permit a user to locate and isolate an item
    without error. Unnecessary details that reduce the comprehensibility
    and clarity of the graphic shall be omitted. \[Source:
    MIL-HDBK-761A, 1989\]

-   **15.5.2.3.4** **Citations of equipment nomenclature.** If a graphic
    contains labels or citations that refer to controls, control
    positions, test points, and indicating devices that are labeled on
    the equipment, the graphic labels shall appear exactly as they
    appear on the equipment (for example, using all capital letters if
    the equipment label does). \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.3.5** **Angle of view.** Graphics shall be drawn from the
    same general angle of view that the equipment presents to a user.
    Cutaways and hidden lines shall be used as necessary in conjunction
    with details that are accessible but not visible to a user. In
    situations in which a user is able to view the equipment from more
    than one angle, the view that provides the most pertinent and
    necessary information in the simplest fashion shall be used. An item
    or part removed from the equipment may be rotated to show important
    features, but, if so, the axis, direction, and degrees of rotation
    shall be indicated in the graphic. Perspective and isometric
    projections shall be used rather than orthographic projection,
    unless the view is head-on. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.3.6** **Use of a human figure.** If it is necessary to
    illustrate an operation or procedure, a graphic shall include a
    human figure or the relevant body parts. Jewelry shall not appear in
    graphics. The human figure or part shall not obscure details of the
    equipment necessary for a complete understanding of its operation.
    The human figure shall be clothed as specified by the acquisition
    program office. A cross section of races and sexes shall be used.
    \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.3.7** **Callouts.** Callouts shall be provided to identify
    specific features of interest on graphics. Callouts shall be in
    accordance with paragraph 15.4.4.5.2. \[Source: MIL-HDBK-761A,
    1989\]

-   **15.5.2.3.8** **Schematic and wiring diagrams.** Unless specified
    otherwise by the acquisition program office, a wire list, schematic,
    or wiring diagram that is displayed in association with text shall
    be simplified to contain only the information referred to in the
    text. However, a user shall have access to the entire wire list,
    schematic, or wiring diagram. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.3.9** **Functional flow diagrams.** Functional flow
    diagrams shall be drawn as flowcharts indicating the direction of
    system interaction. The information shall flow from left to right
    and top to bottom on diagrams. The diagrams shall indicate the
    detail referenced by the accompanying text. \[Source: MIL-HDBK-761A,
    1989\]

-   **15.5.2.3.10** **Locator graphics.** Locator graphics shall enable
    a user to find specific hardware items (for example, parts,
    switches, controls, or indicators) referred to in the technical
    information. A locator graphic shall consist of a labeled graphic
    together with required callouts. The locator graphic shall show what
    a particular item looks like and illustrate its relationship to its
    immediate surroundings on the equipment illustrated. Locator
    graphics, if used, shall either be included as an option for
    selection by a user, or as an automated part of the presentation of
    procedural or descriptive information. \[Source: MIL-HDBK-761A,
    1989\]

-   **15.5.2.3.11** **Placement of locator graphics.** Locator graphics
    shall be integrated with their associated technical information as
    follows:

a.  Individual equipment items (for example, parts, switches, controls,
    and indicators) shall be shown in the physical context of major
    equipment components. The nomenclature of major equipment components
    shall be shown on the graphic.

b.  Index numbers on callouts shall be assigned on the equipment item
    locator graphic either (a) in clockwise sequence, or (b) in the
    sequence that items are discussed in procedural steps.

c.  If a procedural step includes a reference to an illustrated
    equipment item, the reference shall cite either a callout or an
    index number with a leader line pointing to the referenced item.
    \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.3.12** **Exploded item views.** Exploded views of items
    shall be used as locator graphics only if further disassembly is
    required. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.3.13** **Minimum size of a locator graphic.** The minimum
    size of a locator graphic shall enable a user to quickly identify
    the surroundings and the item to be located with respect to the
    surroundings. A callout shall be used to emphasize the item to be
    located. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.3.14** **Animated information.** The motion of animated
    information shall be easily discernable by a user and clearly
    differentiated from its background and from static information on
    display. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.3.15** **Video controls.** If an interactive electronic
    technical manual includes an animated or motion video sequence, the
    sequence shall repeat automatically after completion. A user shall
    be able to pause, repeat, and exit the sequence. \[Source:
    MIL-HDBK-761A, 1989\]

#### 15.5.2.4 Audio {#audio .unnumbered}

-   **15.5.2.4.1** **Redundant visual information.** Audio information
    shall always be accompanied by redundant visual information so that
    the information presentation is effective even if its audio output
    device is not available. Audio information shall be in accordance
    with Chapter 7 of this document. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.4.2** **When to use nonverbal auditory signals.** Nonverbal
    auditory signals shall be limited to applications in which immediate
    discrimination is not critical to personnel safety or system
    performance. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.4.3** **When to use computer-generated and
    electronically-stored speech.** Computer-generated and
    electronically-stored speech shall be limited to the presentation of
    procedural information. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.4.4** **Audio controls.** If an interactive electronic
    technical manual includes either verbal or nonverbal audio signals,
    it shall provide users the ability to (a) request a repetition of
    any signal, (b) adjust the volume of the signals, and (c) turn the
    audio signals on and off. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.4.5** **Pronunciation of abbreviations.**
    Computer-generated and electronically-stored speech shall pronounce
    the entire word or phrase an abbreviation represents unless the
    abbreviation is pronounced as individual letters in common usage.
    Acronyms in common use shall be pronounced as the acronym. \[Source:
    MIL-HDBK-761A, 1989\]

    **Examples.** The abbreviation \"mm\" would be pronounced
    \"millimeter.\" The abbreviation \"SSE\" would be pronounced \"south
    south east.\" The abbreviation SFO (for Sector Field Office) would
    be pronounced \"S\" \"F\" \"O.\" The acronym \"TELCO\" (for
    telephone company) would be pronounced \"telco.\"

-   **15.5.2.4.6** **Pronunciation of alphanumeric strings.** Strings of
    digits or alphanumeric characters that are not ordinarily pronounced
    as a unit shall be pronounced as a series of single letters or
    digits. \[Source: MIL-HDBK-761A, 1989\]

#### 15.5.2.5 Warnings, cautions, and notes {#warnings-cautions-and-notes-1 .unnumbered}

-   **15.5.2.5.1** **When to include warnings and cautions.** If it is
    impossible to avoid the use of or exposure to hazardous materials,
    conditions, or equipment, the technical information shall be
    supplemented with a warning or caution designed (a) to attract the
    user\'s attention to practices, procedures, and conditions that
    could lead to injury or equipment damage, (b) to warn the user about
    the performance of certain hazardous actions, and (c) to state how
    the procedure can be performed safely. Warnings, cautions, and notes
    shall be in accordance with section 15.4.8. \[Source: MIL-HDBK-761A,
    1989\]

-   **15.5.2.5.2** **Readable and comprehensible.** Warnings, cautions,
    and notes shall be easy to read and understand in the work
    environment in which they are likely to appear. \[Source:
    MIL-HDBK-761A, 1989\]

    **Note.** If more than one type of danger may be present, or if
    danger can come from more than one source, or if one type of danger
    may require more than one remedial action, the dangers and actions
    may be referred to once in a single, combined warning or caution.

-   **15.5.2.5.3** **Association of warnings and cautions with text.** A
    warning or caution shall be directly associated with and precede in
    logical sequence the text or procedural step to which it applies.
    \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.5.4** **Location of warnings, cautions, and notes.**
    Warnings, cautions, and notes that are presented in dialog boxes
    shall be displayed in the approximate center of the display area,
    and normal operation of the system shall not resume until a user
    acknowledges the message. Upon acknowledgement, the box shall be
    removed and normal operation resumed. \[Source: MIL-HDBK-761A,
    1989\]

-   **15.5.2.5.5** **Color in warning, caution, and note displays.** If
    color is used in interactive electronic technical manuals, the color
    red shall be associated with warnings, yellow with cautions, and
    cyan with notes. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.5.6** **Borders for warnings, cautions, and notes.**
    Warnings, cautions, and notes presented in dialog boxes shall be
    enclosed in borders consisting of diagonal bars, alternating between
    the background color or white and the designated message color. The
    text shall be displayed within the border. \[Source: MIL-HDBK-761A,
    1989\]

-   **15.5.2.5.7** **When to use notes.** Notes shall be used to supply
    needed information that is not a step in a procedure. Information in
    notes shall be limited to necessary specifics. Required tolerances
    and clearances shall not be given in notes; they shall be included
    in procedural steps. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.5.8** **Association of notes with text.** A note shall
    either directly precede or directly follow the applicable text
    depending upon the point to be emphasized. A note shall precede a
    procedural step to which it applies. \[Source: MIL-HDBK-761A, 1989\]

#### 15.5.2.6 Interaction style {#interaction-style .unnumbered}

-   **15.5.2.6.1** **Dialog boxes.** If windowing is used, a dialog box
    shall be the principal means by which a user interacts with an
    interactive electronic technical manual. The box shall be displayed
    in a separate window and shall contain a heading and one or more
    control push buttons. All boxes shall have an **OK** push button
    and, if appropriate, a **Cancel** push button. Dialog boxes shall
    appear in a consistent and prominent part of the display, and shall
    be easily distinguishable from other types of displayed information.
    \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.6.2** **Dialogs.** Dialogs shall be formulated as prompting
    questions that are presented to the user and that require a response
    from the user. The system response shall be appropriate to the
    user\'s response. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.6.3** **Prompts.** A standard symbol or layout shall be
    used with prompts to indicate to a user that an explicit response is
    expected. The symbol or layout shall be used exclusively for this
    purpose. The user\'s response shall be displayed adjacent to the
    prompt. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.6.4** **Changing responses to prompts.** A user responding
    to a series of prompts in a single portion of a procedure shall be
    able to change any previously entered response as long as that
    change does not alter the logic of the procedure. \[Source:
    MIL-HDBK-761A, 1989\]

-   **15.5.2.6.5** **Navigation operations.** Users shall have at least
    the following navigation functions:

a.  **Next**. This operation shall display the next section of
    information appropriate to the context.

b.  **Back**. This operation, the opposite of **Next**, shall display
    the previous section of information appropriate to the context.

c.  **Return**. If the manual provides branching, this operation shall
    return the user from a branch to the branching point, resetting any
    temporary system state information relative to the branch.

d.  **Browse back, Browse next,** and **Browse exit**. If the Next and
    Back operations set interactive system variables that affect
    subsequent navigation through the manual, browse functions shall be
    available that act as **Next** and **Back** but without affecting
    the system variables. Once the **Browse next** or **Browse back**
    operation has been selected, the normal **Next** and **Back**
    operations shall not be available until the user invokes the
    **Browse exit** operation. The system shall provide a distinct
    visual indication when the system is in the browse mode. \[Source:
    MIL-HDBK-761A, 1989\]

**Definitions.** **Browse back** is the action of moving to the previous
window without permanently resetting system variables; however, system
variables in the temporary state table will be reset. **Browse next** is
the action of moving to the succeeding window without permanently
setting system variables; however, system variables will be set to a
temporary state table. **Browse exit** is the action of leaving browse
mode.

-   **15.5.2.6.6** **Data access operations and features.** An
    interactive electronic technical manual shall provide users at least
    the following access operations or features:

a.  **Marking.** Users shall be able to mark a displayed information
    element for later recall. \"Marking\" shall include the ability to
    create, name, delete, modify, and go to a mark.

b.  **Outline and index.** Users shall have access to information
    through a hierarchical outline of the manual, an index, or both.

c.  **Functional diagrams.** If a manual includes a functional diagram
    or graphic, users shall be able to gain access to information by
    selecting the appropriate portion of the diagram.

d.  **Search.** Users shall be able to gain direct access to information
    by entering selection information in a Search operation.

e.  **Cross-references.** If a displayed information element has a
    cross-reference or other related information associated with it, the
    element shall include a clear indication of that fact, and a user
    shall be able to display the related information and then return to
    the original display using the Return operation (see paragraph
    15.5.2.6.6.c). \[Source: MIL-HDBK-761A, 1989\]

#### 15.5.2.7 User interface

-   **15.5.2.7.1** **Consistency.** The user-manual interaction and the
    display formatting of an interactive electronic technical manual
    shall be consistent across all devices upon which the manual can be
    presented. \[Source: MIL-HDBK-761A, 1989\]

#### 15.5.2.8 Special requirements for proceduralized instructions

-   **15.5.2.8.1** **Form and content.** Procedural information in an
    interactive electronic technical manual shall be directive in form.
    It shall instruct a user how to operate, test, maintain, or repair a
    system. It shall contain the directive information (for example, the
    steps) and any additional supporting material needed or helpful in
    the successful completion of a procedure. \[Source: MIL-HDBK-761A,
    1989\]

#### 15.5.2.9 Special requirements for troubleshooting information

-   **15.5.2.9.1** **Troubleshooting logic.** The fundamental logic for
    interactive troubleshooting shall be specifically designed and shall
    include, but not be limited to, predefined fault isolation sequences
    and dynamically generated fault isolation recommendations based on
    system or user inputs. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.9.2** **Contents.** Troubleshooting information shall
    include, but not be limited to (a) symptoms, (b) procedures, such as
    tests, repairs, and scheduled maintenance, (c) graphics, locator
    diagrams, and schematics, (d) parts and test equipment
    information, (e) equipment failure history, and (f) theory of
    operation. In addition, after a fault has been isolated, the manual
    shall permit direct access to relevant corrective maintenance
    procedures. \[Source: MIL-HDBK-761A, 1989\]

-   **15.5.2.9.3** **User inputs.** Users shall have the following
    capabilities:

a.  the ability to enter symptom information (a) by typing or (b) by
    initiating automatic retrieval from the system or equipment under
    observation,

b.  the ability to enter and change test results, if appropriate,

c.  the ability to confirm conditions or states if necessary to continue
    a user action,

d.  the ability to review and browse through previous actions and test
    results, and

e.  the ability to access information needed to troubleshoot the system
    or equipment in an efficient and clearly defined manner. \[Source:
    MIL-HDBK-761A, 1989\]

-   **15.5.2.9.4** **Predefined fault isolation sequences.** Each step
    in a predefined fault isolation sequence shall be based on the
    reporting of an observed symptom or the result of a previous test
    and shall specify the next procedure, test, or corrective user
    action. \[Source: MIL-HDBK-761A, 1989\]

    **Definition.** A **predefined fault isolation sequence** is a
    sequence of fixed procedures and tests that leads to a suspected
    fault. It is similar to a fault tree in a fault isolation manual.

-   **15.5.2.9.5** **Presentation of a predefined fault isolation
    sequence.** Predefined fault isolation sequences shall be presented
    as procedural steps that prompt users to perform tests, make
    observations, or perform corrective repair actions. \[Source:
    MIL-HDBK-761A, 1989\]

-   **15.5.2.9.6** **Dynamically-generated fault isolation
    recommendations.** Dynamically-generated fault isolation
    recommendations shall be derived from user inputs along with stored
    information and automated inputs. The system shall provide users
    recommendations of tests to perform or actions to perform to aid in
    the fault isolation process. Results of the tests or actions shall
    be used to update the system status and shall result in further
    recommendations, as appropriate. \[Source: MIL-HDBK-761A, 1989\]

    **Definition.** A **dynamically-generated fault isolation
    recommendation** is a recommendation made by a computer system based
    on stored information and information received from user inputs,
    automated system inputs, or both. The information used by the system
    may include historical information, heuristics, probability factors,
    and cost factors. The recommendation may be derived using
    model-based reasoning, dependency models, fault-based reasoning,
    rule-based logic, information theory, or advanced artificial
    intelligence schema.

-   **15.5.2.9.7** **Presentation of dynamically-generated fault
    isolation recommendations.** The starting point for dynamic
    troubleshooting shall be depicted in some representational form, for
    example, a functional or connectivity block diagram. These
    depictions shall convey information about the current components
    under investigation and any suspected faults. By interacting with
    the depictions, users shall be able to obtain additional
    information, such as lower levels of system detail, theory of
    operation, and parts information. Information presentation shall not
    be limited to a single set of troubleshooting recommendations, but
    shall permit users to view additional information such as a \"best
    test\" or \"best repair list,\" previous actions performed during
    the troubleshooting process, test results, and block diagrams.
    \[Source: MIL-HDBK-761A, 1989\]

#### 15.5.2.10 Presentation of parts information {#presentation-of-parts-information .unnumbered}

-   **15.5.2.10.1** **Information available.** An interactive electronic
    technical manual shall include a data base of supporting parts
    information that (a) permits unambiguous identification of all parts
    that are replaceable or repairable at the current level of
    maintenance, (b) shows the precise physical relationship of each
    part to other parts of the system, and (c) provides the user the
    information needed to order parts through the use of an
    automatically-generated parts ordering form. \[Source:
    MIL-HDBK-761A, 1989\]

-   **15.5.2.10.2** **Accessibility of parts information.** Users shall
    be able to access information about a part at any time that part is
    identifiable in a display. Relevant displays include:

a.  locator diagrams.

b.  logic flow diagrams or circuit diagrams.

c.  portions of text that cite the part using any valid designation of
    the part.

d.  a dialog prompt for parts information. \[Source: MIL-HDBK-761A,
    1989\]

-   **15.5.2.10.3** **Direct access.** Users shall be able to obtain
    parts information directly by specifying a part using any applicable
    part identification or numbering system. \[Source: MIL-HDBK-761A,
    1989\]

#### 15.5.2.11 Descriptive information {#descriptive-information .unnumbered}

-   **15.5.2.11.1** **Information available.** An interactive electronic
    technical manual shall include descriptive information to assist a
    user in the comprehension of procedural information. Descriptive
    information shall include, but not be limited to, theory of
    operation, diagrams, and general knowledge. \[Source: MIL-HDBK-761A,
    1989\]

-   **15.5.2.11.2** **Presentation of descriptive information.**
    Descriptive information need not conform to any specified format,
    but shall be easily understandable and usable (see section 15.2).
    Section and paragraph headings shall be employed as needed to assist
    users in identifying or understanding the organization of
    descriptive information (see section 15.2.1). \[Source:
    MIL-HDBK-761A, 1989\]

## 15.6 Accommodating people with disabilities {#accommodating-people-with-disabilities .unnumbered}

> Accessibility in design extends general design principles to cover
> those individuals who are faced with either temporary or permanent
> limitations in some dimension of human ability (e.g., sight, hearing,
> physical mobility, etc.). Although these rules are meant to make
> systems more accessible and thus make systems available to an
> increased number of users, it is not possible to design everything for
> use by everyone. However, there are often adaptations that can
> significantly increase system accessibility and usefulness. The goal
> of this section is to make systems more accessible and thus maximize
> the number of potential users.

**Definitions.** A **disability** is a physical or mental impairment
that substantially limits one or more of a person\'s major life
activities. A **reasonable accommodation** is any modification or
adjustment to a job or the work environment that will enable a qualified
person with a disability to participate in the application process and
to perform essential job functions.

### 15.6.1 Document readability and handling {#document-readability-and-handling .unnumbered}

People with visual disabilities may have difficulty reading printed
documentation, and people with physical disabilities may have difficulty
handling documentation. The following rules provide information that can
be used to design documentation that will maximize the number of people
who can read and handle it. \[Source: Vanderheiden & Vanderheiden,
1991\]

-   **15.6.1.1 Electronic and printed form.** Manuals and other
    important documentation intended to be accessible should be
    available in electronic and printed form and include both text and
    graphic information.

    **Discussion.** This will enable the material to be presented on an
    assisting device such as an enlarged display, a speech synthesizer,
    or a Braille reader. \[Source: Scadden & Vanderheiden, 1988\]

-   **15.6.1.2** **Convertible format.** Documentation should be
    available in formats that can be converted easily. (for example
    ASCII format for normal text) \[Source: Ladner, 1988\]

-   **15.6.1.3 Alternate formats.** Documentation should be provided in
    alternative formats such as electronic, large-print, audiotape, and
    Braille. \[Source: Vanderheiden & Vanderheiden, 1991\]

-   **15.6.1.4 Type size.** Documentation should be provided in the
    largest type that is practical. \[Source: Vanderheiden &
    Vanderheiden, 1991\]

-   **15.6.1.5 Alternate coding devices.** Color coding should not be
    the only coding device used. \[Source: Vanderheiden & Vanderheiden,
    1991, D-1\]

-   **15.6.1.6 Graphic information.** A textual description should be
    provided of all graphical information. \[Source: Vanderheiden &
    Vanderheiden, 1991\]

-   **15.6.1.7 Placement of basic instructions.** Basic instructions for
    operation should be provided on the applicable device and in the
    documentation. \[Source: Vanderheiden & Vanderheiden, 1991\]

-   **15.6.1.8 Compatible documentation.** Documentation should be
    compatible with electronic scanning and optical character reading
    devices. \[Source: Vanderheiden & Vanderheiden, 1991\]

### 15.6.2 Cognitive or language disabilities {#cognitive-or-language-disabilities .unnumbered}

People who have cognitive or language disabilities may have particular
difficulty understanding documentation. The following rules provide
information that can be used to design documentation that will maximize
the number of people who can understand it. \[Source: Vanderheiden &
Vanderheiden, 1991\]

-   **15.6.2.1** **Illustrations.** Descriptions should not require
    illustrations. \[Source: Vanderheiden & Vanderheiden, 1991\]

    **Discussion.** This is especially true for descriptions provided
    for the basic operations. \[Source: Vanderheiden & Vanderheiden,
    1991\]

-   **15.6.2.2** **Key information.** Key information should be
    highlighted and placed near the beginning of the document. \[Source:
    Vanderheiden & Vanderheiden, 1991\]

-   **15.6.2.3** **Instructions.** Step-by-step instructions should be
    provided that use numbers, bullets, or check boxes. \[Source:
    Vanderheiden & Vanderheiden, 1991\]

-   **15.6.2.4** **Directional terms.** When providing instructions,
    directional terms, such as left, right, up, and down should not be
    used. \[Source: Vanderheiden & Vanderheiden, 1991\]

-   **15.6.2.5** **Initiation of basic features.** A section of the
    document should be provided that offers information on how to
    initiate the basic features of the system or equipment. \[Source:
    Vanderheiden & Vanderheiden, 1991\]

**Discussion.** Consider using audio or videotapes in place of printed
documentation to assure that the user is provided the information needed
to operate the basic features. \[Source: Vanderheiden & Vanderheiden,
1991\]

[]{#__RefHeading___Toc23642109 .anchor}Glossary

**Abbreviation** - A shortened version of a word or group of words
formed by omitting one or more letters.

**Acronym** - A word formed from the initial letter or letters of a
group of words.

**Action statement** - An action verb followed by the object or item
acted upon.

**Advance organizer** - Supplementary information that is presented
prior to the main body of information in which a user is interested.

**Appendix** - A body of supplementary information collected, labeled,
and placed at the end of a document.

**Browse back** - The action of moving to the previous window without
permanently resetting system variables; however, system variables in the
temporary state table will be reset.

**Browse exit** - The action of leaving browse mode.

**Browse next** - The action of moving to the succeeding window without
permanently setting system variables; however, system variables will be
set to a temporary state table.

**Caution** - A written notice given when a situation might result in
damage to or destruction of equipment or systems.

**Center-justified text** - Lines are centered on the page, with both
right and left margins ragged.

**Disability** - A physical or mental impairment that substantially
limits one or more of a person\'s major life activities.

**Dynamically-generated fault isolation recommendation** - A
recommendation made by a computer system based on stored information and
information received from user inputs, automated system inputs, or both.
The information used by the system may include historical information,
heuristics, probability factors, and cost factors. The recommendation
may be derived using model-based reasoning, dependency models,
fault-based reasoning, rule-based logic, information theory, or advanced
artificial intelligence schema.

**Figure** - An exhibit that is primarily graphical or pictorial in
nature, as opposed to verbal or numerical.

**Fully-justified text** - Spacing is added within and between words so
that all lines are the same length, resulting in alignment of both right
and left margins.

**Heading** - The title of an organizational subdivision of a document,
that is, a title that has hierarchical significance.

**Indication statement** - States the name of an indicator that the user
reads or observes and the indication expected to result from the action.

**Left-justified text** - Lines of text are aligned at the left, but
spacing within and between words is not varied, resulting in a ragged
right margin.

**Linking sentence** - A sentence that connects the paragraph it is in
to the paragraph that precedes or follows it. The connection is usually
accomplished by repeating a word or phrase or referring to a concept.

**List** - A series of similar or related items in which each item is
marked and displayed on a separate line or lines. The markings can be
graphic symbols, such as bullets () or squares (), or sequential
identifiers, such as numbers or letters. An item can be a word, a
phrase, a sentence, or a group of sentences.

**Mechanical binding** - The pages are punched with either round or
slotted holes and then placed in a ring binder or bound with a comb or
spiral binder.

**Note** - a written notice given to draw the reader\'s attention to
something or to supply additional information.

**Pamphlet binding** - The pages are stitched or stapled together. There
are two types of pamphlet binding, saddle stitched and side stitched.

**Perfect binding** - The pages are assembled, the left side is cut and
roughed, glue is applied, and the cover is attached to the pages.

**Pica** - The unit of measurement used in printing. It is equal to 0.17
inch (4.23 mm).

**Point** - A measure of the height of type; there are 72 points in an
inch (2.54 cm).

**Predefined fault isolation sequence** - A sequence of fixed procedures
and tests that leads to a suspected fault. It is similar to a fault tree
in a fault isolation manual.

**Print contrast** - The ratio of the difference in brightness between
the printing and its background to the brightness of the background
(assuming dark print on a light background). It is defined by
(B1-B2)/B1, where B1 is the brighter of the two.

**Proceduralized instruction** - A set of step-by-step instructions a
procedure intended to ensure the successful completion of a task.

**Reasonable accommodation** - Any modification or adjustment to a job
or the work environment that will enable a qualified person with a
disability to participate in the application process and to perform
essential job functions.

**Right hand page/Left hand page** - The terms right-hand page and
left-hand page have meaning only if pages are printed on both sides. In
that case, a right-hand page is the page printed on the front, and a
left-hand page is the page printed on the back. Thus, when the pages are
bound, and the document is open, the right-hand page appears on the
right, and the left-hand page appears on the left.

**Right-justified text** - Lines of text are aligned at the right, but
spacing within and between words is not varied, resulting in a ragged
left margin.

**Saddle stitching** - A type of pamphlet binding that permits the
document to lie flat

**Serifs** - Decorative elements (short lines, knobs, and balls) at the
ends of the strokes that form letters. Sans serif fonts do not have
these decorative elements.

**Stated indication** - What is expected if the equipment or system is
operating normally.

**Table** - An array of data or text in rows and columns. Usually at
least one dimension, either the rows or the columns, is labeled;
sometimes both are labeled.

**Technical Issuances** - According to FAA Order 1320.1D, are
publications acquired from non-agency sources or developed within FAA
that directly concern installation, maintenance, or modification of
equipment, equipment systems, facilities, or aircraft. Manufacturers\'
instruction books for plants and equipment are included in this
category. A basic objective of using this category is to permit the
merging of internally-developed and externally-acquired technical
manuals and publications into consolidated, single source documents.
Because of necessary deviations from standard directive format and
issuance procedures, they are designated technical issuances.

**Title** - A word or phrase that describes or identifies the contents
of a document or a portion of a document.

**Type family -** A collection of fonts that are similar in design but
vary in size and boldness.

**Warning** - A written notice given to a reader when a situation might
result in personal injury or loss of life; a caution is a written notice
given when a situation might result in damage to or destruction of
equipment or systems; a note is a written notice given to draw the
reader\'s attention to something or to supply additional information.

[]{#__RefHeading___Toc23642110 .anchor}References

American National Standards Institute. (1975). *Electrical and
electronic reference designations.* (ANSI Y32.16). New York: American
National Standards Institute.

American National Standards Institute. (1975). *Standard graphic symbols
for electrical and electronics diagrams*. (ANSI Y32.2). New York:
American National Standards Institute.

Angiolillo, J. S., & Roberts, L. A. (1991). What makes a manual look
easy to use? *Proceedings of the Human Factors Society 35th Annual
Meeting* (pp. 222-224). Santa Monica, CA: Human Factors Society.

Boff, K. R., & Lincoln, J. E. (1988). *Engineering data compendium:
Human perception and performance.* Wright-Patterson Air Force Base, OH:
AAMRL.

Cooper, M. B., Daglish, H. N., & Adams, J. A. (1979). Reader preference
for report typefaces. *Applied Ergonomics, 10* (2), (pp. 66-70).

Department of Defense. (1963). *Designations for electric power
switchgear devices and industrial control devices* (MIL-STD-27A).
Philadelphia, PA: Navy Publishing and Printing Office.

Department of Defense. (1963). *Mechanical symbols* (MIL-STD-17B-1).
Alexandria, VA: Defense Supply Agency.

Department of Defense. (1963). *Mechanical symbols for aeronautical,
aerospacecraft, and spacecraft* use (MIL-STD-17B-2). Alexandria, VA:
Defense Supply Agency.

Department of Defense. (1985). *Specification practices* (MIL-STD-490A).
Philadelphia, PA: Navy Publishing and Printing Office.

Department of Defense. (1988). *Preparation of military standards,
handbooks, and bulletins* (MIL-STD-962B). Philadelphia, PA: Navy
Publishing and Printing Office.

Department of Defense. (1989). *Human engineering guidelines for
management information systems* (MIL-HDBK-761A). Philadelphia: Navy
Publishing and Printing Office.

Department of Defense. (1995). *Manuals, interactive, electronic,
technical: General content, style, format, and user-interaction
requirements* (MIL-M-87268 aka MIL-M-GCSFUI aka MIL-PRF-87268).
Philadelphia: Navy Publishing and Printing Office.

Department of the Air Force. (1980). *Human factors engineering* (AFSC
DH 1-3). Wright-Patterson AFB, OH: ASD/ENESS.

Department of Transportation. (1975). *FAA Glossary* (FAA Order
1000.15A). Springfield, VA: National Technical Information Service.

Department of Transportation. (1984). *Technical instruction book
manuscript: electronic, electrical, and mechanical equipment,
requirements for preparation of manuscript and production of books*
(FAA-D-2494/b). Washington, DC: Martin Marietta Air Traffic Systems.

Department of Transportation. (1992). *FAA Directives system.* (FAA
Order 1320.1D). Springfield, VA: National Technical Information Service.

Department of Transportation. (1992). *Standards for preparing,
printing, and distributing Federal Aviation Administration formal
technical reports* (FAA Order 1700.8D). Springfield, VA: National
Technical Information Service.

Department of Transportation. (1993). *Instructions for writing
equipment and facility directives modifications, maintenance technical
handbooks, and system support directives.* (FAA Order 1320.58).
Springfield, VA: National Technical Information Service.

Federal Aviation Administration. (2000). *Contractions* (FAA order
7340.1). Retrieved March 31, 2000 from the World Wide Web:
http://www.faa.gov/ATPUBS/CNT/CNTHME.HTM

General Services Administration. (1993). *Metric* *units for* *general*
*use by the* *federal* *government.* (FED-STD-376). Washington, DC.,
General Services Administration, Federal Supply Service.

Gribbons, W. M. (1992). Organization by design: Some implications for
structuring information. In *Technical Writing and Communication, 22*,
(pp. 57-75).

Hartley, J. (1978). *Designing instructional text.* New York: Nichols.

Houghton-Alico, D. (1985). *Creating computer software user guides: From
manuals to menus.* New York: McGraw-Hill.

Institute of Electrical and Electronics Engineers. (1984). *Standard
graphic symbols for logic functions* (ANSI/IEEE 91). New York: Institute
of Electrical and Electronics Engineers.

Institute of Electrical and Electronics Engineers. (1986). *Standard
graphic* *symbols for electrical and electronics diagrams.* (ANSI/IEEE
315A). New York: American National Standards Institute.

Institute of Electrical and Electronics Engineers. (1991). *American
national standard letter symbols for units of measurement (SI Units,
Customary* *inch-pound units, and certain other units).* (ANSI/IEEE
260). New York: Institute of Electrical and Electronics Engineers.

Institute of Electrical and Electronics Engineers. (1992). *American
national standard for metric practice* (ANSI/IEEE 268). New York:
Institute of Electrical and Electronics Engineers.

International Organization for Standardization. (1985). *Information
processing \-- Documentation symbols and conventions for data, program
and system flowcharts, program network charts and system resources
charts* (ANSI/ISO 5807). Geneva, Switzerland: International Organization
for Standardization.

Joyce, R. P., Chenzoff, A. P., Mulligan, J. F., & Mallory, W. J. (1973).
*Fully proceduralized job performance aids: draft military specification
for organizational and intermediate maintenance* (AFHRL-TR-73). Brooks
Air Force Base, TX: Air Force Human Resources Laboratory.

Ladner, R. E. (1988). Public Law 99-506, \"Section 508\" Electronic
equipment accessibility for disabled workers \[Panel discussion\]. In
*Proceedings of CHI\'88 Conference on Human-Computer Interaction* (pp.
219-222). New York: Association for Computing Machinery.

[]{.mark}

Rubens, P. (1992). *Science and technical writing: A manual of style.*
New York: Holt.

Scadden, L. A., & Vanderheiden, G. C. (1988). *Considerations in the
design of computers and operating systems to increase their
accessibility to persons with disabilities (Version 4.2).* Madison, WI:
Trace R&D Center.

Simpson, H., & Casey, S. M. (1988). *Developing effective user
documentation.* New York: McGraw-Hill.

Spyridakis, J. H., & Wenger, M. J. (1992). Writing for human
performance: Relating reading research to document deign. *Technical
Communications, 39*, (pp. 202-215).

U.S. Government Printing Office. (1984). *Style Manual.* Washington, DC:
U.S. Government Printing Office.

Vanderheiden, G. C., & Vanderheiden, K. R. (1991). *Accessible design of
consumer products: Guidelines for the design of consumer products to
increase their accessibility to people with disabilities or who are
aging.* Madison, WI: Trace R&D Center.

Wieringa, D., Moore, C., & Barnes, V. (1993). *Procedure Writing:
Principles and Practices.* Columbus, OH: Battelle Press.

Williams, T. R., & Spyridakis, J. H. (1992). Visual discriminability of
headings in text. *IEEE Transactions on Professional Communication, 35*,
(pp. 64-70).

Zaneski, R. (1982). *Software manual production simplified*. New York:
Petrocelli.

[]{#__RefHeading___Toc23642111 .anchor}Index

**A**

Abbreviations 15-14

Accessibility 15-70, 15-71, 15-72

Acronyms 15-14

Adjunct questions 15-6

Appendixes 15-45

Audio 15-63

**B**

Binding 15-19, 15-20

**C**

Capitalization 15-11

Color and shading 15-32

Columns 15-24

Components of documents

appendixes 15-45

copyright and patent issues 15-51

cover page 15-35

figures 15-37

footnotes 15-50

formulas and equations 15-43

glossary 15-46

index 15-46

lists 15-42

lists of exhibits 15-36

publication date 15-51

table of contents 15-35

tables 15-40

tabs 15-50

user feedback forms 15-47

warnings, cautions, and notes 15-44

Content 15-53

Copyright 15-51

Cross referencing 15-7

Cross-references 15-57

**D**

Document hierarchy 15-21

Document level considerations

size 15-18

Document size 15-18

**E**

Exhibit 15-24

**F**

Feedback forms 15-47

Figures 15-37

content 15-39

identification 15-37

location 15-37

orientation 15-39

oversize figures 15-39

style 15-38

Figures and examples 15-3

Flow chart 15-6

Foldout pages 15-25

Font 15-29

Footers 15-20, 15-21

Footnotes 15-50

Format 15-55

**G**

Glossary 15-46

Graphic symbols 15-17

Graphics 15-61

**H**

Headers 15-20, 15-21

Heading 15-4

**I**

Index 15-46

Instructions 15-67

Interactive elctronic technical manuals

descriptive information 15-70

Interactive electronic technical manuals

audio 15-63

graphics 15-61

interaction style 15-65

presentation of parts information 15-69

special requirements for proceduralized instructions 15-67

special requirements for troubleshooting information 15-68

text 15-60

user interface 15-67

warnings, cautions, and notes 15-64

Introductory summary 15-6

Itemization 15-5

**J**

Justification 15-28

**L**

Line length 15-27

Line spacing 15-27

Lists 15-42

**M**

Margins 15-20, 15-21

Mathematical signs 15-17

Measurement *See* Units of measurement

**N**

Numbering 15-5, 15-6, 15-23

Numbers 15-16

**O**

Organization 15-53

advance organizers 15-6

internal cross references 15-7

numbering of sections and subsections 15-5

task versus list orientation 15-7

titles and headings 15-4

**P**

Page level considerations

margins 15-20

Page numbering 15-23

foldout pages 15-24

Paragraphs 15-7

Passive voice 15-10

Phrases 15-11

Point size 15-25

Print size 15-26

Proceduralized instructions

branching and cross references 15-57

format 15-55

miscellaneous 15-57

organization and content 15-53

wording of steps 15-55

Pronouns 15-14

Publication date 15-51

Punctuation 15-11

**R**

Right and left hand pages 15-22

**S**

Sentences

capitalization 15-11

choice of wording 15-8

complexity 15-9

length 15-9

person and mood 15-10

positive, not negative wording 15-10

punctuation 15-11

standard phrases 15-11

voice 15-10

word order 15-9

writing level, readability 15-8

Seriation 15-5

Spacing

text 15-21

Specific user documentation contents

interactive electronic technical manuals 15-58

Spelling 15-16

Standard words 15-13

Symbols 15-17, 15-18

**T**

Table of contents 15-3, 15-6, 15-35

Tables 15-40

content 15-41

formatting 15-41

identification 15-40

location 15-41

orientation 15-42

oversize tables 15-42

Tabs 15-3, 15-50

Terminology 15-12

Text 15-60

Text size 15-25

Title 15-4, 15-5

Type size 15-25

Typographic issues

color and shading 15-32

justification 15-28

line length 15-27

line spacing 15-27

print contrast, quality 15-31

type size 15-25

type style (font) 15-29

typographic emphasis 15-30

upper versus mixed case text 15-29

**U**

Units of measurement 15-16, 15-17

User documentation

components of documents 15-32

layout and formatting 15-18

making documentation appear easy to use 15-3

matching documentation to users 15-2

specific user documentation contents 15-51

writing user documentation 15-4

**W**

Warnings 15-44, 15-64

White space 15-21

Wording

sentences 15-10

Words and symbols

abbreviations and acronyms 15-14

concrete, non-ambiguous words 15-13

consistency 15-12

definitions 15-14

graphic symbols 15-17

letter symbols and mathematical signs 15-17

numbers 15-16

other symbols 15-18

pronouns 15-14

short, high-frequency words 15-12

spelling 15-16

standard words 15-13

units of measurement 15-17

Writing user documentation

organization 15-4

paragraphs 15-7

sentences 15-8

titles and headings 15-4

words and symbols 15-12