Company_Name> Style Guide

<Company_Name> Document Style
Guide
This document contains format and word usage rules for
<Logo> <Company_Name> technical and user documents.
<D_PREFIX>-DocStandard-001
<Month Day, Year>
Prepared for: Prepared by:

<Company_Name> Internal Use Software Engineering Process Group
<Company_Name>
This document was produced by <Company_Name> for internal use.
Document History
Description Author Version Date
Initial issue SEPG <D_PREFIX>- <Month Day,
DocStandard-001 Year>
Customization Information
Delete this section and table when you are done. Don't delete the section break after the table.
Find Replace With: Example

<Company_Name The name of your organization or company: Korestone Technologies
<D_Prefix> The prefix for your document number: KT
<Month Day, Year> The document date in your preferred format: February 16, 2011
<Logo> Image file of your company logo
<!> Find only. Marks section that will need your attention. See also
some instructions enclosed in angle brackets.
Table of Contents
1. Introduction............................................................................................................................................1
Why a Style Guide?...............................................................................................................................1
Scope.....................................................................................................................................................2
Other Resources....................................................................................................................................2
2. Document Structure...............................................................................................................................3
Relationship Between Type Styles and Form..........................................................................................3
The Standard Template..........................................................................................................................4
Standard Styles...............................................................................................................................5
Attaching Templates and Importing Styles.......................................................................................7
Microsoft Word Settings........................................................................................................................8
Page Setup......................................................................................................................................8
Straight Quotes, Ordinal Indicators, and Fractions..........................................................................8
Sections of the Standard Template.........................................................................................................9
Cover..............................................................................................................................................9
Disclaimer Page.............................................................................................................................11
Document History.........................................................................................................................11
Table of Contents and Lists of Figures and Tables.........................................................................12
Summary of Modifications............................................................................................................12
Body of the Document...................................................................................................................13
Acronym List................................................................................................................................13
Glossary........................................................................................................................................14
Appendixes....................................................................................................................................14
3. Mechanics.............................................................................................................................................15
Document Numbers.............................................................................................................................15
Names of Electronic Document Files.............................................................................................15
Margins...............................................................................................................................................16
Headers and Footers............................................................................................................................16
Setting Up Footers to Change at Each Section..............................................................................17
Notes...................................................................................................................................................17
Document Style Guide i

<D_PREFIX>-DocStandard-001 <Company_Name> Document Style Guide <Month Day, Year>
Creating Notes With AutoText.......................................................................................................18

Steps....................................................................................................................................................18
Bullets.................................................................................................................................................19
Graphics..............................................................................................................................................20
Creating Graphics.........................................................................................................................20
Adding Graphics to a Document....................................................................................................20
Tables..................................................................................................................................................21
Captions..............................................................................................................................................22
Cross-references..................................................................................................................................23
Examples.............................................................................................................................................24
Page Breaks.........................................................................................................................................25
Complying With Section 508...............................................................................................................25
4. Style......................................................................................................................................................26
Capitalization......................................................................................................................................26
Capitalization in Titles..................................................................................................................27
Capitalization in Tables and Graphics...........................................................................................28
Capitalization in Proper Nouns.....................................................................................................28
Capitalization in Program and Project Names...............................................................................29
Capitalization in References..........................................................................................................29
Capitalization in Acronyms and Abbreviations..............................................................................29
Capitalization in Computer Terms.................................................................................................30
Use of All Caps.............................................................................................................................31
Punctuation..........................................................................................................................................31
Ampersand (&).............................................................................................................................31
Angle Brackets (< >).....................................................................................................................32
Apostrophe and Possessives (')......................................................................................................32
Asterisk (*)....................................................................................................................................34
Brackets ([ ]).................................................................................................................................35
Colon (:)........................................................................................................................................35
Comma (,).....................................................................................................................................35
Ellipsis ()...................................................................................................................................38
Em Dash ()................................................................................................................................39
En Dash ()...................................................................................................................................39
Hyphen (-).....................................................................................................................................40
Parentheses ( )...............................................................................................................................40
Table of Contents ii
Period (.).......................................................................................................................................41
Question Mark (?).........................................................................................................................42
Quotation Marks (")......................................................................................................................42
Semicolon (;).................................................................................................................................43
Slash Mark (/)...............................................................................................................................43
Other Symbols (, %, #, ", ')..........................................................................................................44
Compounds..........................................................................................................................................44
Spelling................................................................................................................................................47
Acronyms and Abbreviations...............................................................................................................47
Definitions.....................................................................................................................................47
Guidelines for Use.........................................................................................................................48
Numbers and Numerals.......................................................................................................................50
References...........................................................................................................................................53
Referenced Documents Lists.........................................................................................................55
Usage...................................................................................................................................................55
When Style and Screen Disagree...................................................................................................55
When Writing Instructions.............................................................................................................56
Tense.............................................................................................................................................58
Active vs. Passive Voice................................................................................................................59
Words To Mistrust.........................................................................................................................59
Second Person vs. Third Person....................................................................................................60
Phrases That Can Be Reduced.......................................................................................................60
Words That May Not Be Used......................................................................................................62
Formatting...........................................................................................................................................63
Bold..............................................................................................................................................63
Italics............................................................................................................................................64
Online Help Rules................................................................................................................................64
Appendix A. Section 508 Information.....................................................................................................65
Table of Contents iii

List of Figures
Figure 2-1. Cover setup and styles.............................................................................................................10
Figure 2-2. Example document history.......................................................................................................11
Figure 2-3. Sample acronym list................................................................................................................13
Figure 2-4. Sample glossary entry..............................................................................................................14
Figure 3-1. Headers and footers.................................................................................................................16
Figure 3-2. Caption box.............................................................................................................................22
Figure 3-3. Cross-reference box.................................................................................................................23
Figure 3-4. Example example....................................................................................................................24
Figure 4-1. Symbol box.............................................................................................................................38
List of Tables
Table 2-1. Standard styles............................................................................................................................5
Table 4-1. Words not usually capitalized....................................................................................................27
Table 4-2. List of closed prefixes...............................................................................................................46
Table 4-3. Examples of the use of numbers and numerals..........................................................................52
Table 4-4. "See" reference styles................................................................................................................54
Table 4-5. Programmer's perspective vs. user's perspective........................................................................58
Table 4-6. Phrases that can be reduced.......................................................................................................60
Table 4-7. Banned words............................................................................................................................62
Table of Contents iv
1. Introduction
This document attempts to standardize the form and usage in our documents.
Why a Style Guide?

"The devil is in the details."
Anonymous
"God is in the details."

Attributed to Flaubert
Style is essentially a list of details and the way in which each is rendered. In many cases, one way
is as good as another; in all cases, any way can be best, if it is done consistently. This book is here,
at the very least, in the cause of consistency. The fewer misspellings, illogicalities, or
inconsistencies a reader must ignore, the better the reader's impression of a document will be. Our
documents (along with our software) represent our company to our customers, and their quality
determines how we are perceived. In the end, documentation that doesn't make any sense or doesn't
appear to have any thought behind it is just as tiresome as software that doesn't work or that is
poorly designed.
For example, if one time the reader is told to "Pick the File option" and another time to "Click
File," he or she might rightly wonder what differenceif anythere is between the instructions;
indeed, wondering whether there is a difference requires more thought than simply following the
instructions.
Technical manuals are not philosophical meditations intended to encourage wondering. They should
neither distract their readers nor move them to nitpicking. Above all, they should not sidetrack.
Readers who are not distracted use the software more easily and more efficiently.
And should readers nitpick nonetheless, the writer has as his or her defense a standard to which the
document was written. Without a style guide, there is no basis for grammatical, typographical,
stylistic, and other criticismsand likewise, no basis for correcting problems or arbitrating
disputes.
This style guide is an effort to ensure accuracy, quality, readability, and consistency in our
documentation. Conscientious use of this guide will make our documents internally consistent,
easier to read, and less likely to be misunderstood. In short, this guide has as its goal a credible set
of documentation, one that convinces our customers that we have considered the details, major and
minor.
Document Style Guide 1

Scope
This manual applies to all documents produced by <Company_Name> unless the customer or
prime contractor asks us to use another standard. Internal <Company_Name> documents will use
this standard. The style documents address all aspects of documentation, including layout, outlines,
typography, word choice, formatting, acronyms, punctuation, capitalization, and more.
If a style in this manual does not address a situation you encounter in writing a document, find a
solution "in the spirit" of these rules. Likewise, if two styles here seem to conflict, resolve the
conflict with a rule that makes sense and then apply it consistently within your document.
However, rules that are strictly stated in this document are meant to be strictly applied to other
documents. Rules that are somewhat more optional are also stated as such.
Other Resources
Other documents are associated with this style guide:
<Company_Name> Glossary and Acronym List (<D_PREFIX>-DocGloss)<!><An acronym
list is highly recommended for your company.>
3. Mechanics 2
2. Document Structure
All <Company_Name> documents are based on a common set of type styles. The way in which
these styles are used may vary between types of documents, and certain styles may be added or
deleted (either in the template or by a writer) to accommodate the different forms. However, the
idea is that if you can set up and format one document, you should be able to set up and format
them all.
Relationship Between Type Styles and Form

If there were no punctuation marks, sentences would look different. Perhaps the change would be
typographical: each would start on its own line and be limited in length by the width of the page.
Or maybe the difference would be in content: no more than one simple clause would be allowed, for
example. The point is that punctuation influences the set of possible written sentences.
In the same way, the standard set of styles listed in Table Document Structure-1 affects the
possibilities in technical manuals. Take the style "Steps," for example, which is used to indent and
number a series of instructions. If there were no such style, a writer would have two choices:
Make it up.
Write instructions in a paragraph or in another existing style.
The fact that the set of styles described in this document exists should be taken as encouragement
to use those styles. That is, because there is a means by which to indicate the steps in a process, the
writer should, where possible, use the format suggested by that style when he or she needs to write
instructions. Because there is a way to create a bulleted list, the writer should look for ways to use
a bulleted list, and so on.
<Company_Name> Document Style Guide 3

The Standard Template

Note The word "template" often means an outline or basic plan of a document. In this manual,
template means a Word file with the .dot extension that contains the standard styles and the
basic setup of a document.
The document you are reading is based on the standard user's document template, which is named
Doc.dot. This template is kept in Organizational Process Assets\Standards\Style Templates. Also in
that directory is Doc Tech.dot, the template used for technical documents like plans, test
descriptions, design documents, and so on. The main difference: All heading levels are
automatically numbered in the technical document template.
Copy these templates from that directory to the C:\Documents and
Settings\<username>\Application Data\Microsoft\Templates directory on your computer. It will
then be available to you through the New option in the File menu in Word. If the standard template
is updated, you will need to replace your local copy with the newer version.
The templates contain the things you need to start a new document. All the necessary styles are
available via the style box in the Word tool bar, and the cover and front matter are all set up.
There is a difference between type that looks like it is in a style and type that actually is in that
style (i.e., the name of the style appears in the style box when the cursor is on that type). The
difference is that if a type of style needs to be adjusted, you can make a change to the style one
time (via the Style option on the Format menu) rather than going through the entire document and
making the same change at every instance of the style. (Note however that ad hoc deviations are
permitted for reasons like fitting something on a page, space after tables, and other cases.)
The other reason for the use of styles is that they are easier to use. It is simpler to select something
from a list than to format each line of text, and it is much easier to keep the type styles consistent
throughout the document. And when you have to fix something that a programmer or manager
wrote using who-knows-what format, it takes much less time.
3. Mechanics 4
Standard Styles
Table Document Structure-1 lists the basic styles used in the main templates.
Table Document Structure- 1. Standard styles

Style Name Definition Where Used
Acronym list Normal + Line spacing: single, Space After: 4 pt Acronym table
Bullet 1 Normal + Indent: Left: 0.25", Hanging: 0.25", Space After: First-level bulleted list
6 pt, Tabs: 0", List tab, Numbered + Level: 1 + Numbering
Style: Bullet + Start at: 1 + Alignment: Left + Aligned at:
0.25" + Tab after: 0" + Indent at: 0.5"
Bullet 2 Normal + Indent: Left: 0.5", Hanging: 0.25", Line spacing: Second-level bullet under Bullet
At least 12 pt, Space After: 6 pt, Numbered + Level: 1 + 1
Numbering Style: Bullet () + Start at: 1 + Alignment: Left
+ Aligned at: 0.5" + Tab after: 0" + Indent at: 0.75"
Bullet Steps Bullet 1 + Indent: Left: 0.5", Tabs: 0.75", List tab + Not at First-level bullet under Steps
0", Bulleted (11 Pt) + Level: 1 + Aligned at: 0.5" + Tab
after: 0.75" + Indent at: 0.75"
Bullet Steps 2 Bullet 2 + Indent: Left: 0.75", Tabs: 1", List tab, Bulleted + Second-level bullet under Bullet
Level: 1 + Aligned at: 0.75" + Tab after: 1" + Indent at: 1" Steps
Caption Normal + Font: Calibri, 10 pt, Italic, Centered, Line Under pictures or figures
spacing: single, Space Before: 3 pt
Caption-tables Caption + Space Before: 6 pt, After: 3 pt, Keep with next Above tables
Cover Date Doc # + Space Before: 0 pt, After: 60 pt Coverdate
disclaim Normal + Font: Italic, Space Before: 186 pt, After: 0 pt Disclaimer
Doc # Normal + Font: Calibri, 14 pt, Bold, Line spacing: single, Coverdocument number
Space Before: 48 pt, After: 0 pt
Doc Title Normal + Font: Calibri, 28 pt, Bold, Space Before: 100 pt Coverdocument title
Footer Normal + Font: Calibri, 9 pt, Right: 0", Line spacing: single, Footer region (page number) on
Space After: 0 pt, Border: Top: (Single solid line, Blue- pages after the first page of a
Gray, 0.5 pt Line width), Tabs: 6.5", Right section
Footer-first page Footer + Centered Footer region of first page of a
section
Glossary entry Normal + Indent: Left: 0.25", Hanging: 1" Glossary items and definitions
Header Normal + Font: Calibri, 9 pt, Font color: Gray-80%, Right: Header region
0", Line spacing: single, Space After: 0 pt, Border: Bottom:
(Single solid line, Blue-Gray, 0.5 pt Line width), Tabs:
3.25", Centered + 6.5", Right
Heading 1 Normal + Font: Calibri, 18 pt, Bold, Kern at 14 pt, Right: Chapter headings
0", Line spacing: At least 18 pt, Space Before: 60 pt, After:
12 pt, Keep with next, Level 1, Border: Top: (Single solid
line, Gray-50%, 0.5 pt Line width), Bottom: (Single solid
line, Gray-50%)
Heading 1A Heading 1 + None, No bullets or numbering Level 1 heading that appears in
TOC but is not numbered
(appendix title)
3. Mechanics 5

Heading 1X Heading 1 + None, No bullets or numbering Level 1 heading that is not
numbered(e.g., "Contents")
Heading 2 Normal + Font: Calibri, 14 pt, Bold, Right: 0", Line spacing: Level 2 headings
At least 14 pt, Space Before: 18 pt, Keep with next, Level 2
*
Heading 2X Heading 2 + None Level 2 heading that is not
numbered
Heading 3 Normal + Font: Arial, Bold, Italic, Right: 0", Line spacing: Level 3 headings
At least 12 pt, Space Before: 15 pt, Keep with next, Level 3
*
Heading 3X Heading 3 + None Level 3 heading that is not
numbered
Heading 4 Normal + Font: Calibri, 12 pt, Right: 0", Line spacing: At Level 4 headings (do not appear
least 12 pt, Space Before: 12 pt, After: 6 pt, Keep with in TOC)
next, Level 4 *
Normal Times New Roman, 11 pt, English (U.S.), Right: 0.5", Line General text
spacing: At least 11 pt, Space After: 9 pt, Widow/Orphan
control
Normal after Normal + Space Before: 3 pt After bullet or step to start new
paragraph
Normal before Style for Next Paragraph: Bullet 1; Normal + Space After: Before a bulleted list
bullet 6 pt, Keep with next
Normal before Style for Next Paragraph: Steps; Normal before bullet + Before a numbered list (steps)
step
Normal Normal + Space Before: 6 pt, After: 6 pt On a normal line after a bullet
between bullets or step and before another
bullet or step
Normal indent Normal + Indent: Left: 0.5", Space After: 6 pt Continuation of step or bullets
Prepared... Normal + Font: Calibri, Line spacing: single, Space After: 0 Cover"Prepared by" and
pt "Prepared for"
RTM Normal + Indent: Left: 0", Hanging: 1.5", Tabs: 1.5", Left Requirements quotation
Screen Normal + Right: 0", Centered, Space Before: 3 pt, After: 0 Picture or figure
pt, Keep with next
Source Normal + Font: Courier New, Condensed by 1 pt, Indent: Quotations from programming
Left: 0.25", Line spacing: single, Space After: 2 pt language, other computer things
Steps Normal + Indent: Left: 0.25", Hanging: 0.25", Space After: Instructions
6 pt, Numbered
Steps indented Steps + Indent: Left: 0.5", Tabs: 0.75", List tab, Numbered Instructions under bullets
+ Level: 1 + Numbering Style: 1, 2, 3, + Start at: 1 +
Alignment: Left + Aligned at: 0.5" + Tab after: 0.75" +
Indent at: 0.75"
Table of Figures Normal + Indent: Left: 0", Hanging: 0.33", Space After: 6 In lists of figures and lists of
pt tables
Table text Normal + Font: Calibri, 10 pt, Right: 0", Line spacing: In tables
single, Space Before: 1 pt, After: 1 pt
Table text 8 Table text + Font: 8 pt In table; smaller type
3. Mechanics 6

Table text bullet Table text + Indent: Left: 0.05", Hanging: 0.25", Tabs: 0.3", Bullets in table text
List tab, Bulleted + Level: 1 + Aligned at: 0.05" + Tab after:
0.3" + Indent at: 0.3"
Table text Table text + Indent: Left: 0", Hanging: 0.25", Tabs: 0.5", In tables; numbering and tab
numbered 1 Left after number are not automatic
Table text Table text numbered 1 + Indent: Left: 0.25", Hanging: 0.5" Second-level numbering in
numbered 2 tables; numbering and tab after
number are not automatic
Table text Table text numbered 2 + Indent: Left: 0.5", Hanging: Third-level numbering in tables;
numbered 3 0.75", Tabs: 1", Left numbering and tab after
number are not automatic
Title explain Normal + Font: Calibri, Right, Space Before: 6 pt, After: 6 Covertext under title
pt
TOC 1 Normal + Font: Bold, Space Before: 6 pt, After: 6 pt, Tabs: TOC line for Heading 1 and
0.25", Left + 6.5", Right, Leader: Heading 1A
TOC 2 Normal + Indent: Left: 0.25", Space After: 6 pt, Tabs: 6.5", TOC line for Heading 2
Right, Leader:
TOC 3 Normal + Indent: Left: 0.5", Space After: 6 pt, Tabs: 6.5", TOC line for Heading 3
Right, Leader:
TOC 4 Normal + Indent: Left: 0.5", Tabs: 6.5", Right, Leader: TOC line for Heading 4 (not
required)
* Heading numbering for levels 2 and lower is turned on for technical documents.
Attaching Templates and Importing Styles

When formatting or editing a document that was not created using the standard styles or one of the
templates, there are two ways to make the process easier and faster:
Attach a TemplateAttaching a template brings all the styles from the template to the existing
document and replaces styles with the same names with the styles from the template. To attach a
template
1. From the Tools menu, select Templates and Add-Ins. The Templates and Add-Ins window
appears.
2. Click Attach. The Open window appears.
3. Browse for the template you want to attach, highlight it, and click Open. The Templates and
Add-Ins window reappears.
4. Click OK. The new template is attached and the styles it contains are available.
Import StylesThis method seems less reliable than attaching a template, but works well if you
need to copy a few selected styles from one document to another. To import styles:
1. From the Tools menu, select Templates and Add-Ins. The Templates and Add-Ins window
appears.
2. Click Organizer. The Organizer window appears.
3. Click Close File under the list on the rightnot under the list on the left. The panel above the
button empties.
4. Click the same button, which is now called Open File. The Open window appears.
3. Mechanics 7
5. Browse for the file or template from which you will import styles. Highlight it and click Open.
The Organizer window reappears.
6. Highlight the styles in the list on the right that you want to import. Then click Copy (the
button between the two lists). The styles marked for import should appear in the list on the left.
If one of the styles being imported has the same name as an existing style, a confirmation box
appears. Click Yes or Yes to All to overwrite existing styles.
7. Click Close. The Organizer window disappears.
Microsoft Word Settings

Each writer likes his or her computer and software set up in a certain wayand we're not even
considering choice of screen saver here. This section makes no attempt to change the appearance of
the Word interface or to mess with the writer's personal preferences. However, a few settings
should be consistent throughout the company. These include:
Page setup
Straight quotes, ordinal indicators, and fractions
Page Setup
Margins, headers, and footers should be standardized. If a document is created from a template,
these settings take care of themselves. However, it may be necessary to make adjustments in some
cases. To do this, select Page Setup from the File menu. Then
On the Layout tab, make sure Section Start is set to New Page, and that in the Headers and
Footers region, Different first page is selected while Different odd and even is cleared.
On the Margins tab, make sure Top, Bottom, Left, and Right are set to 1" and that Gutter is set to
0". Make sure that in the From Edge area, Headers and Footers are both set to 0.5". Finally, make
sure that the Mirror margins checkbox is cleared.
Straight Quotes, Ordinal Indicators, and Fractions

Our documents use only straight quotes and apostrophesnot the "smart" variety of these items.
Also, use regular text instead of the Word-imposed ordinal indicators and fraction characters. To
make your computer use the right things:
1. From the Tools menu, select AutoCorrect. The AutoCorrect properties sheet appears.
2. Click the AutoFormat As You Type tab.
3. In the Replace as you type area, clear three checkboxes: "Straight quotes" with "smart quotes";
Ordinals (1st) with superscript; and Fractions (1/2) with fraction characters.
4. Select this checkbox: Symbol characters (- -) with symbols ().
5. Click OK.
Note To replace smart quotes already in a document with straight quotes, perform
the steps above, then select Replace from the Edit menu. When the Replace
window appears, enter " in both the Find and Replace fields, then click
Replace All. Repeat with the single quote (') in both fields.
3. Mechanics 8
Sections of the Standard Template

This section goes through the basic parts of a document in the order in which they generally
appear. Documents includeat mostthe following items, in this order:
Cover
Disclaimer page
Document history
Table of contents, list of figures, list of tables
Summary of modifications (release notes only)
Body of the document
Acronym list
Glossary
Appendixes
The sections below indicate which of these sections are mandatory and which are included only
with certain documents.
Cover
The standard document templates come with the cover page already set up. The cover pages
include the following information:
TitleUser's manuals should be titled with the application name first, then the type of document:
Our Great System v7.4 User's Guide, for example. All other documents should use the type of
document first, then the application name: System Test Description for Our Newest System v7.5.
Spell out the type of document and the application rather than using the acronym in the title. Use
the style Doc Title. For long titles, you may reduce the font size.
SubheadingIn the format called Title explain, this sentence or two states the purpose of the
document. Use both spelled-out names and acronyms here for the application. For example: "This
plan outlines the software quality assurance activities to be performed during the Sort Program
System (SPS) v7.4 project lifecycle." This text goes in the right column of a two-column row in a
table with invisible borders.
Document NumberThese are explained in "Document Numbers" in Chapter 3. The style is Doc
#.
DateRemember to spell out the month. The style is Cover Date.
AddressesThere are two addresses on the cover of a document: ours, and the address of the
customer department for which the document was written. Our address is under the label "Prepared
by:"; the customer address is preceded by "Prepared for:". Both addresses are inside an invisible
table of one row and two columns. The "prepared" lines in each address block and the addresses
are in the style Prepared, with the "prepared" lines in bold.
The cover has no page number, no header, and no footer. Tables with no borders are used to lay out
the page. There is a section break after the second table.
3. Mechanics 9
Figure Document Structure-1 shows how it works.
Figure Document Structure- 1. Cover setup and styles
3. Mechanics 10
Disclaimer Page
Use the style disclaim, and set up the page for bottom alignment.
The disclaimer text for a customer document is:
This document was produced by <Company_Name> for <Customer_Name>. Distribution
is authorized to <Customer_Name> only; this document may not be reproduced or used, in
whole or in part, outside <Customer_Name> without permission from the agency listed on
the cover. This restriction does not limit the <Customer_Name>'s right to use information
contained within.
For in-house documents, use this disclaimer:

This document was produced by <Company_Name> for internal use only
Document History
This page is used to record the differences and changes between the current document and the
previous version of the document. This may involve replacing a single page, a pair of chapters, or
the entire document. Whenever anything is changed from the previous releaseincluding page
numbersthe change must recorded here.
The heading "Document History" is in the style Heading 1X. The remainder of the page is a
standard table (see "Tables" in Chapter 3) with four columns: "Description," "Author," "Version,"
and "Date." The column widths are as follows: 2.3"; 1.9"; 1.2"; and 1.2"
When a document is first issued, the Description column entry is "Initial issue." Thereafter, this
column lists the pages that were replaced, added, or deleted for that version. Use the entire
document number in the Version column of the first entry. Thereafter, use only the version and
change number. Figure Document Structure-2 is an example.
Description Author Version Date

Initial issue Engineering Group (C. Jones) K-SPEW-SUM-001 February 15, 2001
Revised Chapter 3 based on Engineering Group (R. -002 May 16, 2002
ephemeral whims Oppenheimer)
Changed Chapter 3 based on sudden Technical Writing Group (F.S. -002-C1 May 17, 2002
reversal of whim Fitzgerald)
Figure Document Structure- 2. Example document history
Place a paragraph return after the table, then insert a section break. As with the disclaimer page,
the document history has no page number and no header or footer. Should a document be around
long enough and go through enough revisions, it is permissible for the history to run more than one
page. Never delete information from a previous document history, lest you diminish its "historic"
nature.
3. Mechanics 11
Table of Contents and Lists of Figures and Tables

The first page of the table of contents is numbered "i". The second-page footer has the words
"Table of Contents" at the left margin and the page number at the right margin. The standard table
of contents goes three levels deep; that is, Heading 3 titles are included, but Heading 4 titles are
not. Heading 1 titles are represented by the style TOC 1, Heading 2s by TOC 2, and Heading 3s by
TOC 3. Every document must contain a table of contents.
If a document contains one or more figures, the titles of the figures and the page on which each
appears must be listed in the Contents section of the document. This list follows the main table of
contents. The title"List of Figures"is in the style called Heading 2X. The items in the list use
the style Table of Figures.
If a document contains one or more tables, the these must be listed, along with their page numbers,
in the Contents section of the document. If a document includes both a list of figures and a list of
tables, the list of tables follows the list of figures. The title "List of Tables" is in the style called
Heading 2X. The items in the list use the style Table of Figures.
There should be a section break following the last list in this section.
Note The titles of appendixes are included in the table of contents, but the subheadings (i.e.,
level 2 and below) need not be. See "Glossary," below, for information on the formatting
that makes this not only possible but automatic. Likewise, the tables and figures in
appendixes are generally not enumerated in the list of tables and list of figures.
Summary of Modifications
The summary of modifications section is included only in release notes. The title "Summary of
Modifications" is set as Heading 1A. This section is used to outline the major changes involved in
the release in question.
If there are subheadings in either a preface or summary of modifications, these should not be
included in the table of contents.
If the document is compliant with the government's Section 508, include this section in the Preface
(for more information, see the Section "Complying With Section 508."):
Section 508 Compliance
This documentation conforms to the accessibility standards of section 508 of the
Rehabilitation Act of 1973, as amended 29 U.S.C. 794 (d). All images in this document
contain alternative text. Every table is accessible by screen reading technology.
For more information on section 508, contact the Center for IT Accommodation (CITA),
Office of Government-wide Policy, U.S. General Services Administration.
Address:
1800 F Street NW
Room 1234
Washington, D.C. 20405
E-mail: section.508@gsa.gov
Telephone: 202-501-4906
3. Mechanics 12
Fax: 202-501-6269
Website: www.section508.gov
Body of the Document

Chapter headings are always numbered, but the subheadings in each chapter (Heading 2, Heading
3, etc.) are numbered only in technical documents. The first page of Chapter 1 is page "1," and the
numbering runs continuously throughout the document. There is no indication in the page number
of what chapter the page belongs to (i.e., no page 2-1, etc.), but the footer changes in each chapter
to reflect the chapter number and title. (See "Headers and Footers" in Chapter 3.)
Many documents have a standard outline. Templates are generally located in the Business Process
System directory under the process area to which they apply.
Acronym List
All user's guides, release notes, and technical documents need an acronym list. The acronym list
may be part of the final section of the document or may be an appendix to a document. The section
title is "Acronyms and Abbreviations," and the title is formatted depending on its location.
The only text required between the title and the list of acronyms is this: "The following acronyms
and abbreviations are used in this document as defined here."
The body of the acronym list is a normal two-column table. The left border should be at the left
margin of the page. The first columnthe one that contains the acronymis 1" wide. The second
column is 5.4" wide. The headings of each column ("Acronym" and "Definition," respectively) are
marked as headings so that they repeat at the top of each successive page. The style of the text in
the table is Table Text; bold the column headings.
Figure Document Structure-3 shows a sample acronym list.
Acronym Definition
BCS barcode sorter
OGP outgoing primary
Figure Document Structure- 3. Sample acronym list
3. Mechanics 13
Glossary
The glossary may be an appendix to a document or be part of the last section of the main body of
the document. This section is optional. The glossary is titled "Glossary," oddly enough, and the title
is formatted according to its location in the document. In another weird twist, glossary entries are
formatted using the style called Glossary entry. Bold the name of the term, and capitalize only
proper names and other words capitalized in the <Company_Name> Glossary and Acronym List.
If a glossary definition is not a complete sentence, don't put a period at the end of it unless there is
more than one sentence or fragment in the definition. Figure Document Structure-4 shows a sample
entry:
alias fileA file that contains up to seven variations of a primary street name to accommodate
common misspellings and abbreviations
Figure Document Structure- 4. Sample glossary entry
Appendixes
Appendixes follow the last chapter or section of the body of the document. Page numbering in
appendixes continues from the last page of the previous section. Use an appendix for material that
if included in the main document would disrupt the flow or for material that is useful but not
crucial to what is being discussed in the main document.
The title of an appendix is in the style "Heading 1A." This means that it appears in the table of
contents, but that it is not automatically numbered. Headings at level 2 and 3 are the unnumbered
Heading 2X and Heading 3X and do appear in the table of contents.
Figures and tables in appendixes must be numbered "by hand"not with Word's automatic caption
numbering feature. The figures and tables in an appendix should not be listed in the document's
contents section. They should be numbered with the appendix's letter (rather than a section
number): for example, the second table in Appendix C would be Table C-2.
3. Mechanics 14
3. Mechanics
Document Numbers
Document numbers are used by the Configuration Management (CM) group to keep track of
documents under their control. If you have a question about a document number, ask someone in
CM to help you assign one to your document. The numbers are in the following form:
<D_Prefix>-AAAA-SSS-XXX-CN
The variables in this format stand for the following information:

AAAA is the project acronym. It may have more or less than four characters, depending on the
project, and may include the version number. Examples are "SPS75" and "FUIS11."
SSS is the abbreviation for the type of document. Examples: "RN" for release notes, "STD" for
system test description.
XXX is the document version numbernot the software version number. For example, the first
time a document is released, its version number is "001." The next version is "002." If a document
is a draft, append a "(D)" to the end of this number: "001(D)." The version number should always
have 3 digits.
CN is the change number. If a change is made to the document but the version does not change, add
"C" and the number of the change to the end of the document number (e.g., "C2").
You can add "-DRAFT" to the end of a document number while it is in draft form.
Thus, for the second batch of changes to the first edition of the software development plan for OBS
v7.5, the document number would be <D_Prefix>-OBS75-SDP-001-C2.
Note Use hyphens in document numbers rather than en dashes or em dashes.
Names of Electronic Document Files

The document number becomes the name of the electronic document file, as well, except for the
version and change number. For example, a document whose number is <D_Prefix>-OBS75-SRS-
001 should be saved as <D_Prefix>-OBS75-SRS.doc. If a document number includes a slash,
replace the slash with an underscore (_) in the electronic document name. User's guides are
generally not numbered, so their file names are <Project> User's Guide.doc.
Margins
These are controlled using the Page Setup option in the File menu, but should already be in place if
you're working from a template. The margins in our documents are 1" on all sidestop, bottom,

left, and rightleaving a text area of 6.5" by 9". The settings in the From Edge area should be 0.5"
for both Header and Footer.
Headers and Footers

The cover, disclaimer page, and document history pages do not have headers or footers. Other
headers and footers will be as shown in Figure Mechanics-5.
All text in both the headers and footers is 9-point Calibri, Gray-80%. The styles are Header and
Footer. There is a blue-gray line on the inside of the header or footer.
Beginning with the table of contents, the first page of a section does not have a header, but does
have a footer. The first-page footer includes the document title at the left margin and the page
number at the right margin (right tab at 6.5").
The second and subsequent pages of a section have both a header and a footer. The latter-page
header includes the document number at the left margin; the document title (centered); and the
document release date at the right margin. The document name should use title capitalization.
The latter-page footer has the chapter or section number and title at the left margin and the page
number at the right margin.
Figure Mechanics- 5. Headers and footers
If the first page and following pages of a document have the same headers and footers:
1. In the File menu, select Page Setup. The Page Setup properties sheet appears.
2. Click the Layout tab if the Layout page is not already visible.
3. On the Layout page, select Different first page.
4. Click OK. You can then add different information on the first page of that section.
Setting Up Footers to Change at Each Section

Footers contain the section or chapter number and name. This means that the footer must change
from section to section. To accomplish this feat:
1. View the document in Print Layout view. To do this, select Print Layout from the View menu.
3. Mechanics 16
2. Insert a section break at the end of a chapter. To do this, move the cursor to the line after the last
line of the chapter. From the Insert menu, select Break. In the Break box that appears, select Next
Page under Section Break Types. Then click OK.
3. Double-click in the footer that you want to change. The Header/Footer toolbar appears.
4. Click the Same as Previous button to clear that optionthat is, it should be turned off. (The
button shows two small pages with a dotted line connecting the footers of the pages.)
5. Enter the new footer information.
6. Repeat the steps to change the footer of the next section.
Notes
Notes are used to include information that is somewhat tangential, not unlike that found in a well-
used footnote. They could also include warnings to the user, a reminder of things that must be done
prior to doing the steps that follow, or other things of that sort. Use the following information to set
up a note:
The standard note is a table consisting of one row and two columns. The borders are all invisible.
The first column is 0.55" wide and shaded Gray-12.5%; the second column goes to the right
margin.
o When a note appears among steps, bullets, or other indented paragraphs (like here), you should
align them with the left margin of the paragraphs preceding/following it. This would indicate
that the note is specific to that item rather than the entire process. Therefore, it would look
something like this (because this is an indented paragraph):
Note Indented note.
The text in both columns is Normal style.

In the left-hand column, type Note (or another word, like Hint or Warning). Make the word bold.
If the Note has multiple items, type Notes and use bullets or steps in the right-hand column.
Do not allow a note table to break across a page.
3. Mechanics 17
Creating Notes With AutoText
You can have Word create the Note table for you by using the AutoText feature. First you define
the entry, then you can use it.
To define the AutoText entry (you need to do this only once):
1. Create the note table and text you wish to use as a model and highlight it.
2. In the Insert menu, select AutoText, then click AutoText. The AutoCorrect box opens with the
AutoText tab active.
3. In the box Enter AutoText entries here, type a codeword that you will use when you want to insert
a note (something like "nbx" for a normal notebox). Don't use a real word.
4. Click Add.
Note The code "nbx" and a corresponding AutoText entry has been added to the
<Company_Name> Doc.dot and <Company_Name> Doc Tech.dot templates. If
your document is based either template, you should be able to see these in the
list of AutoText entries.
To use the AutoText entry:

1. At the place where you want the note table, type the codeword you used for the normal note
("nbx" in the example above).
2. Press F3 (or, if the tooltip prompts you, press Enter). The notebox is inserted.
Alternately, if you like using the mouse, you can do this:

1. Place the cursor where you want the note table to be inserted.
2. In the Insert menu, select AutoText, then click AutoText. The AutoCorrect box opens with the
AutoText tab active.
3. From the list of AutoText entries, select the one for the note. You should see the notebox in the
Preview box.
4. Click Insert. The notebox is inserted.
Steps
Use the style Steps when writing step-by-step instructions. The line before the first step should be
in the style Normal before step; never use steps without an introductory line (something in the "to-
do-this-follow-these-steps" vein). The line after the last step (if there is one) should be in the style
Normal after bullet. To write a second paragraph of a step (without a number), use the style called
Normal indent.
See "When Writing Instructions" in Chapter 4 for more information on writing steps.
Bullets
Unlike steps, bullets are not used for instructions, but rather for lists where the order of the items is
not crucial. The primary bullet style is Bullet 1. A subpoint to a first-level bullet is Bullet 2. Bullets
3. Mechanics 18
may also be used under a step: the styles are Bullet Steps and Bullet Steps 2. Use the style Normal
indent for a second paragraph under a first-level bullet. You may use a single bullet (rather than a
list) to mark a point of information subordinate to the preceding sentence or paragraph. (There are
several examples of this in this very style guide.)
Normal text that precedes a bullet should be formatted as Normal before bullet. Text following a
bullet is Normal after bullet, unless the text is a continuation of the paragraph that introduced the
bulleted list. (In the latter case, use plain old Normal.) Regular text that both follows and precedes
a bullet is formatted as Normal between bullets.
Do not interrupt a set of bullets with a figure or table. Place the figure or table after the complete
list of bullets instead.
Sometimes a bullet has a title-like word or phrase followed by an em dash, followed by information
that expands on the "title." Do not use another punctuation mark (e.g., a colon) for bullets like
these; always use the em dash with no spaces on either side of it. Capitalize these titles as if they
were headingssee "Capitalization in Titles" in Chapter 4.
Bulleted lists should be introduced using, in some manner, the words "the following <nouns>,"
followed by a colon. Do not use "following" as anything other than an adjective; this means that
there must always be a noun after it for "following" to describe. Examples of list introductions
include the following phrases:
The committee plans to perform the following tasks:
This indicates the following conditions:
Examples of incorrect answers include the following blunders:
For variety, you may occasionally use an introductory phrase that does not include "the following,"
but the above forms are preferred.
If each bullet in your list has a lot of information that goes with it, it might be easier to list the
topics or "titles" in a bulleted list without the information, and then to use a separate section for
each nominated topic. For example, the bulleted list might include the different options on a certain
application menu. It would then be followed by one lower-level subsection for each option named
in the list.
Notes Do not append "and" or "or "to the next-to-last item in a list.
See "Periods in Lists" in Chapter 4 for information on punctuation in bulleted lists.
3. Mechanics 19
Graphics
Graphics are most effective if they are not overused. It is not necessary to show a screen in every
step, especially if only minor changes occur from one step to the next. Save graphics for when
there is really something to show. (That's what they mean in all those television warnings about
"graphic" contentthere's something to show.) And show it wellread something by Edward
Tufte to gain a sense of what really doesn't need to be shown in a graphic.
Creating Graphics
The majority of the graphics used in documents are screen shots. To take screen shots, use SnagIt
or a similar program.
Graphics come in a variety of formats. The graphical interchange format (.gif) seems to supply a
satisfactory picture while requiring only a fraction of the memory space needed by a bitmap
(.bmp). SnagIt can be set up to save shots as .gifs, and that format is the one you should use.
Sometimes, a screen shot or other picture needs to be annotated (i.e., with lines pointing out
various features) or the document needs a diagram or schematic drawing. For these purposes, use
Visio. Do not use the drawing feature in Word for this purpose, as disasters are likely to happen.
Adding Graphics to a Document

Refer to a graphic in the text prior to its appearance. If necessary, explain the figure after it
appears. Do not assume that the gist your masterpiece is as obvious to everyone as it is to you.
To add screen shots to a Word document:
1. From the Insert menu, select Picture, then select From File. The Insert Picture box appears.
2. Navigate to the saved graphic and click Insert. The picture is inserted in the document.
3. Add alternative text if required. For details, see Appendix A.
To insert a Visio diagram:

1. Open the diagram in Visio. Click somewhere on the page that is not part of the diagram, and press
Ctrl+C.
2. In Word, place the cursor where you want the diagram to go.
3. From the Edit menu, select Paste Special. The Paste Special box appears.
4. Select Picture (Enhanced Metafile). Then click OK.
5. Add alternative text if required. For details, see Appendix A.
Both pictures and diagrams should be formatted with the style Screen. Add a caption below a
graphic as explained in "Captions," below. Do not put the title of a graphic inside the graphic itself;
that is, an organization chart should not say "Organization Chart" at the top of the graphic and in
the caption.
3. Mechanics 20
Tables
Refer to a table in the text before it appears. That is, the "see" reference should come before the
table. Be sure to explain its contents, however briefly; don't assume that the table is self-
explanatory.
The text in a table is in the style Table text When applicable, use Table text bullet. You must
manually boldface the table's header row. Text in a table is left justified; however, you may center
an ordered column of numbers or right justify a column of monetary values or other numerals as
necessary. Both exterior and interior borders are 1/2 point. You can also insert a table in a
document that was started from one of the standard templates by typing JK_Table and then Enter.
The following options are useful in managing tables:
If the table will span a page break, mark the first row as "headings." To do this, click anywhere in
the first row. Then from the Table menu, select Heading Rows Repeat. The selected row then
appears at the top of each page that the table is on.
In most cases, it is best to prevent rows of a table from splitting across a page break. To keep each
row together, highlight a column in the table and select Properties from the Table menu. On the
Row page, clear the Allow row to break across pages checkbox. Also on that page, clear the
Specify height checkbox.
Table headings should always be in the middle of their cells, vertically speaking. This means, for
example, that if some of the headings in a table have two lines and others have one line, you must
format the headings as centered vertically using the Table menu or toolbar. (It isn't necessary to do
this if all the headings contain the same number of lines.)
Table captions go above the table and are in the style Caption-tables. Insert the caption as
explained in "Captions," below.
To ensure that our published user documents comply with Section 508, keep the table as simple as
simple as possible. That is, do not create a row that spans multiple rows beside it, nor a column
that spans multiple columns below it. Screen reading software such as JAWS gets confused with
complex tables. For more information, see Appendix A.
The Table feature in Word can also be used to lay out text. A table with only invisible borders can
make text easier to manage than it would be if you tried to do it with hanging indents, tabs, and
indentations. For example, the title and address blocks on the are laid out with tables, as are
noteboxes. Experiment and see whether an invisible table can save you some time. These invisibly
bordered tables should not receive a caption.
3. Mechanics 21
Captions
Both tables and figures require captions. A table caption goes above the table; a figure caption
follows the figure. Both are numbered with the chapter number (or appendix letter), a hyphen, and
the number of the figure or table within that chapter. For example, the second table in Chapter 3 is
"Table 3-2." A period follows the number of the figure or table, then one space, then the title of the
table or figure (using an initial cap and then regularnot titlecapitalization rules).
Tables with invisible borders (e.g., noteboxes, tables used only for layout purposes) do not receive
captions and numbers. An acronym list likewise has no caption.
Word allows you to insert automatically numbered captions that will update their own numbers if
you add or remove another table or figure. If you do not use this process to insert captions in the
body of a document, you cannot use automatic cross-references to refer to them, and it takes a little
more work to automatically generate list of figures or lists of tables.
Note For captions in appendixes, type them in manuallydo not use the Insert Caption option
explained below. This will prevent appendix tables and figures from being listed in the list
of tables or list of figures and will allow you to use the letter of the appendix in the
caption (e.g., Table B-1). Cross-references to these tables and figures must be typed in and
updated by hand.
To insert an automatically numbered caption, move the cursor to where you would like the caption
to go. Then:
1. Select Caption from the Insert menu. The Caption box appears (Figure Mechanics-6).
Figure Mechanics- 6. Caption box
2. The Caption box is used for all kinds of labels.

If you are adding a caption to a table, select Table from the Label list.
If you are adding a caption to a figure, select Figure from the Label list.
The Caption field shows the type of label selected and automatically knows the number the
figure or table should have.
3. In the Caption field, type the period after the number, a space, then the caption.
4. Click Numbering. The Caption Numbering box appears. Make sure these fields are set as follows:
Format1,2,3
3. Mechanics 22
Include chapter numberCheckbox is selected

Chapter starts with styleHeading 1
Use separator(hyphen)
5. Click OK in the Caption Numbering box, then click OK in the Caption box. The boxes disappear
and the caption is inserted at the cursor.
6. All captions are automatically inserted in the style Caption.
If you are inserting a caption for a figure, you are done.
If you are inserting a caption for a table, put the cursor anywhere in the caption and select
Caption-tables from the Style list.
Cross-references
Automatic cross-references can be based on headings, bookmarks, figures, or tables. Using
automatic cross-references means that you no longer have to go through the document and change
all the numbers when you insert a figure or move a tableWord does it. Note, however, that to
cross-reference a figure or table, you must first insert the caption for the table or figure using the
process in "Captions," above.
Note For the structures to use when making reference to other parts of a document or to other
documents, see "References" in Chapter 4.
To insert a cross-reference, move the cursor to where you would like the reference inserted. Then:
1. From the Insert menu, select Cross-reference. The Cross-reference box appears (Figure
Mechanics-7).
Figure Mechanics- 7. Cross-reference box
2. In the Reference Type list, select the type of item to which the cross-reference should refer (e.g.,
table, figure, heading, bookmark). The list of available objects of this type appears in the large list
below.
3. Clear the checkbox Insert as hyperlink.
4. In the For Which Caption list (the large list at the bottom of the window), select the item to which
you want to refer.
3. Mechanics 23
5. In the Insert Reference To list, select the style of cross-reference. The choices in the list vary based
on what was selected in the Reference Type list. The word "label" refers to "Table" or "Figure";
thus, the option Only Label and Number inserts, for example, "Table 4-2." The other choices are
fairly self-explanatory.
6. Click Insert. The cross-reference is inserted at the cursor.
Examples
When describing the way a software application works, use examples of the application in actual
practice to make your point more clear. Examples, in this case, are not the steps necessary to
perform a task; rather, examples complement procedures by providing scenarios in which a user
undertakes a task. Write all examples in the present tense.
Introduce an example with the word "Example" in bold, followed by a period not in bold. The style
is Normal. Include an example number if more than one scenario is being provided for a given task
(e.g., Example 1.). Do not number all examples throughout a document consecutively; consecutive
numbering applies only to each task. Begin the scenario on the same line as the word "Example,"
as shown in Figure Mechanics-8.
Example. There is a massive snowstorm outside and an SPS user has to alter sort programs to
meet a revamped delivery schedule and also because of that "neither rain or sleet" part of his
contract.
Figure Mechanics- 8. Example example
Note When writing examples, talk about a single user and arbitrarily make a decision as to the
gender of this user. Do not sacrifice grammatical rules to inclusiveness; for example, do
not write "the user opens their application" as this means one person has opened an
application owned by a pronoun with a plural antecedent, which is not the case. Write
instead "the user opens her application" (one user, singular pronoun). The next time you
have an example, make it a male user. Or don't. No one is keeping score.
3. Mechanics 24
Page Breaks
There are several cases where you should insert a page break to make text more readable:
Unless a figure occupies an entire page, keep the figure reference that introduces it on the same
page as the figure itself. Unless a figure takes up an entire page, it should never appear at the top
of a page; text should always precede it.
Never let a bulleted or numbered item start on one page and conclude on the next. Insert a page
break before that item. The same applies to the second paragraph under a bulleted or numbered
item (i.e., one in the Normal indent style). For the purposes of this rule, consider a bulleted item or
numbered item to include all the paragraphs that are part of the same bullet or step.
Never let a table start on one page and continue on the next unless that table is too long to fit on
one page. When necessary, insert a page break before a table reference to ensure that a table fits on
one page.
The following guidelines are not absolute, but using them is preferred to not using them:
Consider making an entire list (whether bulleted, numbered, or any other type) fall on one page as
long as doing so does not leave too little text on the page preceding the list. Make certain to insert
the page break before all relevant text that precedes the list (e.g., introductory paragraphs and
headings).
If a heading appears near the bottom of a page (e.g., two-thirds of the way down the page or
lower), consider inserting a page break before it, particularly if the section of text that the heading
introduces could fit on one page.
Complying With Section 508

Accessibility, as defined in Section 508 of the Americans with Disabilities Act, may be required on
some project documents. If the section does apply, note that it only applies to user documents.
Steps for ensuring document and help system accessibility are in Appendix A.
3. Mechanics 25
4. Style
This section includes the finer points of punctuation, capitalization, compound words, hyphenation,
numbers and numerals, and word usage.
Capitalization
Our style uses minimal capitalization. The most-used rule is that generic terms are not capitalized.
For example:
the Open option
the Print window
the Sort Programs page
a technical writer
the mail processing machine
mail level F
machine type D
Classes of words that are capitalized include:

The names of options, windows, and menus
o the Edit option; the Create File window; the Tools menu
o Exception: the main menu (it's a description, not a title)
The names of software applications, unless the manufacturer or developer notes otherwise
o Image Verification System software; the Search Tool utility; Our Better System
Names of important divisions of an application
o Automated Editor, City/State Table
o But: for a data file of the same name, the generic term is not capitalized, as in "City/State
table"
The names of company departments or groups
o Configuration Management group; Quality Assurance group
o Exception: Software Engineering Process Group ("group" is part of this committee's name,
rather than a generic designation)

Capitalization in Titles
Articles, prepositions, and conjunctions in a title are lowercased when they consist of four letters or
less. The word "to" is capitalized when it is part of the infinitive form of the verb, but lowercased
when it is used as a preposition. Verb particles (e.g., "up" in "back up") are capitalized, even
though they are lowercased when used as prepositions.
The first and last words of a title are always capitalized.
Note Negating words like "not" and "no" are capitalized in titles, but "nor" is not
capitalized.
These rules apply not only to the titles of documents and sectionsnot to the captions for figures
and tables.
In titles, generic terms are capitalized, unlike in text. For example:
Creating a File
Opening Text.dat
Table Style-2 shows commonly used words that are not capitalized in titles.
Table Style- 2. Words not usually capitalized

Articles Prepositions* Conjunctions
a at of and
an by on but
the for onto nor
from to or
in up
into via
of with
* Unless part of a verb (e.g., Set Up)
The style allows introductory titles after a bullet and followed by an em dash. The following rules
apply to the capitalization of these titles:
The title itself follows the capitalization rules for headings, unless it is a sentence.
The first letter after the em dash is capitalized. For example:
o Technical ProblemsIf test equipment is not used properly, something will go wrong.
3. Mechanics 27
Capitalization of Hyphenated Words in Titles

When hyphenated compounds appear in a title or heading, use the following rules:
Capitalize all words of the compound in headings except when one of the words is a preposition, an
article, or a conjunction.
o FactorytoCustomer Delivery
o Add-on Functions
o Application-Specific Features
Do not capitalize the second part of prefixed, hyphenated words.
o E-mail Service
o Cross-references
Capitalization in Tables and Graphics

For table column headers, the rules for the capitalization of titles apply. For information in the cells
of a table, generally just capitalize the first word. Use a period after sentences, but no punctuation
after fragments (unless the cell contains more than one fragment).
Treat text in graphics as if it were a title, unless it is a sentence or a phrase of five words or more.
Capitalization in Proper Nouns

Capitalize the following items:
All proper nouns
o Potomac River
o United States Postal Service
o The University of Southern North Dakota at Hoople
Titles of client or <Company_Name> groups or departments
o Engineering Research Division
o Technical Writing group
Note Generally, a position title is not capitalized unless it precedes a proper name.
Chief Executive Officer Joe Sampson
Joe Sampson, chief executive officer, takes us out to lunch almost every
month.
3. Mechanics 28
Names of calendar divisions

o April, May, June
o Monday, Wednesday, Friday
Note Seasons are only capitalized when followed by a year.
The software malfunctioned badly in the winter. Must have been the
cold.
Winter 1997 (Not: "Winter of 1997" or "Winter, 1997")
Capitalization in Program and Project Names

The words "program," "project," and "contract" are not capitalized unless the word is part of an
official title. For example:
The city contract
The program manager reports to the project manager.
The subcontractor was assigned to the development program.
Capitalization in References
The initial letters of the words "figure," "table," "chapter," and "section" are capitalized in specific
text references. Do not capitalize "step," "page," or "subsection," in references, as illustrated in the
following examples:
as shown in Figure 2-1, page 21.
See Section 4.
See subsection 4.1.3.
Note For the definitions of "chapter," "section," and "subsection" and other information on
making references to other parts of a document or to other documents, see "References,"
below.
Capitalization in Acronyms and Abbreviations

Use capital letters as required in acronyms and abbreviations, as shown in the following examples:
BRM
Ph.D.
etc.
The plural marker (s) on an acronym is in lowercase. For example:

RBIs
VDTs
3. Mechanics 29
Capitalization in Computer Terms

Computer terms have some special capitalization rules.
Keyboard Items
Use initial capital letters for keys on the computer keyboard. Do not use quotation marks or angle
brackets to indicate keys on a PC. The names of keys with no name are lowercase. For example:
Press N.
Press Delete.
Press the space bar.
Press the up arrow key.
In a key sequence, such as when Ctrl and another key must be pressed at the same time, connect
the different keys with a plus sign (and no spaces). For example:
Press Ctrl+Alt+Delete.
Screen Items and Choices

Use lowercase letters for generic computer descriptions such as fields, functions, or utilities. The
following rules apply:
The names of options and buttons should be capitalized as they appear on the screen, unless they
are all caps on the screen and not an acronym. (In that case, use only an initial cap, which is what
the programmer should have done anyway. The exception is "OK.")
For boldfaced options or checkboxes with names consisting of three or more words, keep the
capitalization as it appears on the screen, but precede the name of the option with "the option" or a
related indication:
o Select the option I know all.
o Select the checkbox Don't detect my printer, I will select it from a list.
For the names of screen items that are not boldfaced, you may change the capitalization
from that on the screen. For example, a field labeled as "For which heading:" on the screen
could be "the For Which Heading field" in the document. See "When Style and Screen
Disagree," below, for more information.
3. Mechanics 30
Use of All Caps

Classifications are in all caps. For example:
SECRET
Do not use all caps to emphasize a worduse italics instead, as shown in the following examples:
Click Close File under the list on the rightnot the list on the left.
Leave all the keys in place except for the "W."
Certain computer languages require all capital letters. Use them as necessary. However, if the
system does not require all caps, use mixed case.
Punctuation
Proper punctuation clarifies the meaning of words. Improper punctuation confuses the reader.
Sometimes the clearest punctuation is no punctuation at all. Think about it.
The highest authority on punctuation use is The Chicago Manual of Style, unless this guide says
something to the contrary.
In general, set colons, commas, periods, and semicolons in normal, nonbold typeeven when a
neighboring word is boldfaced or italicized. If punctuation appears inside a bold or italicized
phrase or sentence or is part of a quotation, format it to match the passage. However, in an
instruction like "Press Enter.", the period is not bold. The main reason for this is that Word does
not select the neighboring punctuation when you highlight a word or simply place the cursor in it
and press Ctrl+B; thus, it is faster to leave the trailing punctuation as normal text.
Ampersand (&)
You should use an ampersand only when it is part of a company's formal name, such as "AT&T."
In general, do not use the ampersand as a substitute for the word "and." Only a few acronyms use
an ampersand:
IV&V
3. Mechanics 31
Angle Brackets (< >)

Angle bracketsgreater-than and less-than symbolsare used to enclose situation-specific
variables in a screen message, entry, or other instruction as shown in the following examples:
A message appears on the screen: Now checking <server>.
Enter the directory name C:\Stuff\Computer\Things\<username>, where <username> is the name
of the user.
Note Treat variables within angle brackets as words. If possible, use only
one word inside the brackets to avoid giving the impression that
there is more than one item to be substituted for the variable. Use all
lowercase letters. Words within angle brackets may be shortened for
space considerations, so long as the abbreviation is consistent
throughout the step and explanatory material.
There should be no space between a bracket and the material inside it; there should be one space on
the outside of a bracket in the normal flow of text.
Apostrophe and Possessives (')

Use an apostrophe followed by an s to form the possessive of singular nouns, abbreviations, and
acronyms. For example:
Steve's new car
FTP's quirks
Form the possessive of singular nouns, plural nouns, and plural acronyms that end in an /s/ or /z/
sound by adding an apostrophe only. For example:
agencies' policies
the Dawsons' papers
the PCs' Ethernet addresses
Form the possessive of common plural nouns not ending in s by adding 's as shown in these
examples:
businessmen's notes
management's decision
Use an apostrophe followed by an s to form the plural of abbreviations with more than one period.
M.A.'s and Ph.D.'s
3. Mechanics 32
Do not use an apostrophe to form the plural of acronyms, letters, numbers, or abbreviations with
only one period. Only use an s, as shown here:
As and bs
yrs. (plural of "yr.")
RFPs
In compound nouns, add an apostrophe followed by an s to the element nearest to the object being
possessed (so to speak). For example:
Mr. Jordan of Washington's delusions
Indicate joint possession by placing an apostrophe on the last element of a series. However,
individual or alternative possession requires an apostrophe on each element of a series as illustrated
by the following examples:
managers', supervisors', and aides' qualifications (i.e., each person has qualifications)
Get a writer's or editorial assistant's opinion. (i.e., get one opinion or the other)
Dr. Roberts' and Mr. Porter's conference papers (i.e., there are two papers)
Bill, Jack, and John's report (i.e., all three worked on the same report)
Use the authentic form for geographic names, firm names, organization and institution names, and
the titles of books, articles, and so forth. In general, things named for people get no apostrophe
when the eponymous individual is dead. For example:
Harpers Ferry
Meems Bottom Bridge
In general, use an apostrophe to indicate contractions and the omission of figures or letters as
shown in the following examples, which would be used only when abbreviation were really
necessary:
Cont'd (for continued)
FY '10 (for Fiscal Year 2010)
Exceptions: "mgmt." (for "management"); "mgr." (for "manager"); "phone" (for "telephone")
Do not use an apostrophe when adding a suffix to an acronym. For example:

FTPing, FTPd
Use an apostrophe followed by an s in possessive indefinite or impersonal pronouns. For example:

each other's plans
someone's application
Use an apostrophe followed by an s to form the possessive case of nouns preceding a gerund (i.e., a
noun formed from a verb by adding "-ing"), as illustrated here:
"The decision was changed" becomes "The decision's being changed"
3. Mechanics 33
"The staff reached a conclusion" becomes "The staff's reaching a conclusion"
Use an s followed by an apostrophe to indicate the archaic (in English, anyway) genitive case.
Rather than worrying about whether something is indeed of the genitive case, just look at the
following examples:
five years' experience (i.e, five years of experience)
one hour's delay (i.e., a delay of one hour)
1 million dollars' worth (i.e., worth 1 million dollars)
Do not use an apostrophe to form possessive pronouns like the following examples:
its (However, the contraction of it is is "it's." Please don't screw this one up.)
ours
Do not use an apostrophe to form the plural of spelled-out numbers, words referred to as words, or
words already containing an apostrophe. For example:
threes, fives, and eights
ups and downs
yeses and nos
dos and don'ts
Asterisk (*)
Use an asterisk to refer the reader to an explanatory statement. The referring asterisk should be
placed at the end of a sentence, after the punctuation mark, as in this sentence:
Check your e-mail messages at least three times daily.*
The information to which the asterisk refers is preceded by an asterisk and placed at the bottom of
the page (like a footnote); directly below a table (if the referring asterisk is in the table); or inside a
figure (if the referring asterisk is in the figure). The sentence might look like this:
*This applies only to on-site employees.
Do not use "star" to mean asterisk, except when referring to the key on a telephone pad.
3. Mechanics 34
Brackets ([ ])
Use brackets in the following situations:
To set off parenthetical matter within parentheses
o (the Requirements Traceability Matrix [RTM])
In mathematical equations
o [x + (y-1)] (x+y)
As needed in OpenVMS to show directory structures
o $ set def DRT:[DMS_DISK]
There should be no space between a bracket and the material inside it; there should be one space on
the outside of a bracket in the normal flow of text.
Colon (:)
Use a colon in these situations:
To introduce a quotation
o A box appears with a warning: Pressing Enter will restart the system and kill us all!
Before a numbered series of instructions, a bulleted list, or shorter list or series
o There are three kinds of barcodes: POSTNET, PLANET, and ID Tag.
o The following rules apply:
o Follow these steps to start the application:
Each line of material presented in a numbered or bulleted list after a colon begins with a capital
letter. But if other information after a colon consists of more than one sentence, is a formal
statement, or is a quotation, it should also begin with a capital letter. (For an example, see the first
bullet in this section.)
There should be only one space after a colon, and no space before it.
Comma (,)
Commas are used in the following spots:
After each term in a series of three or more terms with "and," "or," or "nor" before the last term
o addressing, postage, sorting, and delivery
Following "that is" or the abbreviations "i.e." and "e.g."
o Cease all operationsthat is, stop workingright now.
o Making sure the equipment (e.g., display units, digitizers, and communications consoles)
arrives is part of the fun.
3. Mechanics 35
o The performance review (i.e., the one that determines whether I get a raise) will take place on
Thursday.
Note Do not use a comma preceding the abbreviation "et al." (meaning "and
others"), except in a series.
Puckett et al.
Hrbek, Puckett, Gagne, et al.
To set off appositives or other nonessential words, phrases, or clauses
o Mr. Jackson, the chief engineer, will conduct the test.
o In 1952, when the company was formed, a research division was not considered essential.
o She put much thought into her choice of a desktop theme, a new option in Windows 98.
o He delivered the document, which was truly a piece of crap, to the customer with his apologies.
Before "and," "but," "or," "nor," or "yet" when they join two complete thoughts
o All of the material was tested as required, and the results of the tests were logged.
o The computer should be plugged in, but it should not be turned on.
Note There should be a subject and a verb on both sides of the comma (in
sentences using one of the coordinating conjunctions listed above). If both
subject-verb sets are short and closely related, however, the comma is not
required:
Ed wrote and Drew fixed up the graphics.
Multiple objects or predicates relating to only one subject do not require a

comma to separate them unless a comma is required to make the meaning
of the sentence plain.
Bill has been delivering mail for years and knows lots of dog stories.
To separate phrases and avoid misunderstanding

o Before starting, the car coughed several times. (Could be read incorrectly as: Before starting
the car)
o For testing, the computers were upgraded. (Could be read incorrectly as: For testing the
computers)
Note If the initial clause or phrase is short and there is no possibility of
misreading, omit the comma.
When the mail comes the test will start.
but
When the mail comes from Cleveland, the test will start.
To separate two or more adjectives modifying the same noun
o A high-voltage, low-impedance power source
o Paul cut down the old oak tree. ("Oak tree" is a unit.)
o Paul cut down the old, yellow-ribboned oak tree.
3. Mechanics 36
o The new work requirement made us put in long overtime hours. ("Overtime hours" is a unit.)
Note Omit the comma when the first adjective modifies the second or when the
second adjective and the noun are thought of as a unit.
Tests: If you can replace a comma with "and," it is correct. If you can
reverse the order of the modifiers, you can use a comma between them.
To separate into 3-digit groups Arabic numerals containing 4 or more digits
o 3,434
o 12,921
After the year in complete dates within a sentence
o The conference meeting on February 6, 2008, was successful.
o The statistics for December 1, 1996, through February 1, 1997, were incorrect.
Note Do not use a comma in month-year combinations.
The April 1996 figures are not available.
Before and after a state name or abbreviation (if preceded by a city name), and before and after
"Inc.," "Ltd.," or "LLC."
o <Company_Name>, LLC, is located in Fairfax, VA.
To separate a proper name from a following academic, honorary, governmental, or military title
o Steve Godshall, M.D.
o But: Kyle Rote Jr. or Chester B. Groggleschlomp III
Commas are placed inside of quotation marks, but go outside of parentheses and brackets, and
after semicolons. If placing a comma inside the quotation marks would change the name of an
option or affect something that is to be typed, the comma may be moved outside of the quotation
marks.
3. Mechanics 37
Ellipsis ()
Use an ellipsis (three periods in a row) to indicate the omission of words. If an ellipsis comes at the
end of a sentence, add another period (i.e., the one you would usually use at the end of the
sentence) for a total of four. Do not include the ellipsis at the end of a Windows option name or
button name. Examples include the following situations:
Read the paragraph beginning "In this chapter, we will."
"Friends, Romans, countrymen" is the wrong way to start a technical manual, though it does have a
certain ring.
From the Format menu, select Style. (The option is "Style" on the screen.)
An ellipsis is actually a special character in Word. Using it will take care of the age-old question of
how to space the periods. The keyboard shortcut to insert an ellipsis is Alt+Ctrl+Period. You can
also set up Word to automatically replace three consecutive periods with an ellipsis by using the
AutoCorrect option in the Tools menu. Alternatively, use the Insert menu:
1. Place the cursor at the point where you would like to insert the ellipsis.
2. From the Insert menu, select Symbol. The Symbol box appears (Figure Style-9).
Figure Style- 9. Symbol box
3. On the Special Characters tab, click Ellipsis.

4. Click Insert. An ellipsis is added to the document. Click Cancel to close the box.
There should be no space before the ellipsis. If the sentence continues, there should be a space
between the ellipsis and the next word. If the ellipsis concludes the sentence, the fourth period
follows immediately after the ellipsis, with no intervening space.
3. Mechanics 38
Em Dash ()
To add an em dash in Word, hold down Ctrl+Alt, then press (the dash or minus sign) on the
number pad. (You can also set up Word's AutoCorrect feature to replace two hyphens with an em
dash.) Or, follow the steps above for inserting an ellipsis (but select the em dash instead). To insert
an em dash in PowerPoint or Excel, hold down Alt and type 0151 on the number pad.
Use an em dash:
To mark a sudden change in thought or the flow of the sentence
o The softwareboy, did it stink!failed to operate properly.
To set off an explanation
o The systemdesigned, installed, and testedwas due today.
In sentences with several elements referred to by the same indicative pronoun
o Sorting, dispatch, and deliverythese are the areas covered by this manual.
Do not use a space on either side of an em dash.
En Dash ()
To produce an en dash in Word, hold down Ctrl and press (the dash or minus sign) on the
number pad. Or, follow the steps above for inserting an ellipsis (but select an en dash instead). To
insert an en dash in PowerPoint or Excel, hold down Alt and type 0150 on the number pad.
The en dash is used:
To indicate a range or inclusive set of numbers. However, in text, the word "through" is preferred
to the en dash.
o Pages 3133 (In text: pages 31 through 33)
o September 31November 8 (In text: September 31 through November 8)
Note Do not use an en dash for "to" when "from" precedes the expression or for
"and" when "between" precedes the expression.
From 3 June to 3 July (not from 3 June3 July)
Between 1994 and 1996 (not between 19941996)
In a compound modifier, in place of a hyphen when one of the elements is a nonhyphenated
compound or two or more of the elements are hyphenated compounds. (See "Compounds," page
44.)
o postWorld War II
o nonUSPS-related contracts
o the New YorkBoston rivalry
3. Mechanics 39
To indicate a relationship involving a transfer of information

o usermachine interface
As a minus sign
Do not use a space on either side of an en dash.
Hyphen (-)
Hyphens are used to separate the elements of a compound, if it is supposed to be hyphenated. (See
"Compounds," page 44.)
Hyphens are also used in addresses, telephone numbers, document numbers, figure and table
numbers, spelled-out fractions, and ZIP Codes. Examples:
7451-B Javier Ave.
(703) 941-6444
K-BPS11-STD-001
Figure 2-4
one-fifth of an ounce (but one fifth of scotch)
22060-5260
Do not use a space on either side of a hyphen.
Parentheses ( )
Parentheses are used in the following situations:
To set off a reference
o The resistors are mounted on a card. (See Figure 2-16.)
o The Sort screen appears (Figure 6-9).
To set off examples
o The parts (e.g., capacitors, resistors, and switches) are off-the-shelf items.
To announce the first use of an acronym
o Our Great System (OGS) is used to
For other amplifying, explanatory, or digressive phrases
o When reading documents late at night (as happens from time to time), change the typeface to a
larger point size.
Avoid wherever possible the use of parentheses to indicate a possible plural, as in "mistake(s)." The
regular plural ("mistakes") will almost always suffice. If this would result in a grammatical or
logical error, write out both forms ("mistake or mistakes") and conjugate the verb using the second
word.
There should be no space between a parenthesis and the material inside it; there should be one
space on the outside of a parenthesis.
3. Mechanics 40
Period (.)
The period marks the end of a declarative sentence, like this one. Also use it at the end of an
imperative sentence, like this one. Use only one space after a period. The use of the period is also
governed by the following rules:
Use periods with abbreviations but not with acronyms. Always use periods when abbreviating
United States (U.S.) when talking about the country, but not in "USPS."
If a sentence ends with a computer command or directory path and a final period could be
construed as part of the command, leave the period off. If possible, get this period-less item to go at
the end of a paragraph or line.
o In the Drive field, type Tmp/DNS.NIS.fix/Inst
Use a period after the table or figure number in a table or figure caption.
Figure 2-1. Fake figure caption
If an entire subsection of a document consists of a single sentence fragment, use a period after the
word or phrase. This rule does not apply to short phrases in tables or figures.
4.2.8 Management Recommendations
Not available.
Use a period after letters and figures in an outline, in footers, and in step numbers, but do not use a
period after the number of titles Heading 2 level or lower.
o II. (Roman numeral)
o 5. Style (in footer or as Heading 1)
o 5.3 Rules and Regulations (as Heading 2)
Use a period inside parentheses when they enclose a complete sentence, but put the period outside
the parentheses when the enclosed material is not a complete sentence.
o Many of the reviewers who plan to attend the meeting have other commitments. (These
commitments include golfing, sleeping, and playing online games.)
o For information on the situation, contact Engineering Software Management (a division of the
USPS).
Periods should not be used in the following situations:

Following a title or header
In tables and graphics except after a complete sentence
Certain cases in lists as described in "Periods in Lists," below
Periods in Lists
Use a period at the end of a bulleted or numbered item that is a complete sentence. Use no
punctuation at the end of an item that is not a complete sentence. Do not consider the phrase that
introduces the list when deciding whether something is a sentence. That is, if the words in the item
are only a sentence when combined with the introductory words, do not use a period at the end of
the item. Do not use a period after the final item in the list simply because it is the final item in the
list. Try to write the list so that all items in it are either sentences or not sentences.
3. Mechanics 41
Question Mark (?)

Use a question mark after a direct question, as in this example:
What are youstupid?
Do not use a question mark after an indirect question, as shown here:

Ask who is providing the bagels and coffee and find out what's taking so long.
Quotation Marks (")

Use only "straight quotes"not smart quotes.
Quotation marks are used to enclose the words of a speaker or writer, as shown here:
The employee newsletter stated, "Take time to marvel at the wonders of life." So Jack asked, "Can
we count that on our timesheets?"
If a word, idiom (e.g., "the right stuff"), or a noun phrase (i.e., a noun along with its article and
modifiers) must be set off from the other words of a sentence, use quotation marks as in the
following example:
Use "among" instead of "between" when speaking of more than two entities.
However, use italics to set off a longer phrase or sentence used as an example, or to indicate a
letter or number standing as a noun. For example:
Instead of writing The system displays the data, write The data appears.
The Ss and 5s look lousy in that font.
Note In using punctuation marks with quoted words, phrases, or sentences,
always place the period or comma inside the quotation marks. Place the
colon or semicolon outside. Dashes, question marks, or exclamation points
are placed inside if they pertain to the quoted matter only, but outside if
they have bearing on the entire sentence. For example:
The text uses the phrase "is comprised of," but "comprises" is correct.
Meg said, "Do you plan to leave soon?"
Did Meg say, "I plan to leave soon"?
Semicolon (;)
Use a semicolon in these situations:
To separate independent clauses not joined by "and," "but," "or," "nor," or "for"
o All of the material has been tested; the results have been logged.
Prior to adverbs (e.g., "then," "however," "thus," "besides," "therefore") used as a transition
between the clauses of a compound sentence
o The program should run on its own; however, if something goes wrong, call me.
To separate independent clauses, at least one of which contains commas
3. Mechanics 42
o The output amplifier contains an input network, a voltage divider, and two power tubes; and it
operates from a commercial power supply.
Between items in a series if one or more of the items contain a comma
o The test team has responsibilities like preparing test documentation; testing, analyzing, and
evaluating the software and hardware; assisting in resolving program deficiencies; and
documenting test results.
Slash Mark (/)

Note To impress your friends, call this symbol a "solidus" or "virigule."
There are no spaces on either side of the slash mark. Use the slash mark for the following reasons:
To represent "per" in certain abbreviations
o 60 in./h.
o 10 ft./sec.
To show the marked positions of switches, buttons, or keys
o Set the On/Off switch to On.
To show alternative meanings or choices
o To begin a system/software specification (SSS)
Note Avoid "and/or." Use one or the other, or rewrite the statement.
In fractions
o 1-1/2 points
To separate components in an OpenVMS file name, path name, or command
o /h/DMSDDS/Scripts/config_dds.dtksh
o run vdc_main/nodebug
Note File names and path names in Windows use a backslash (\).
C:\Program Files\Word\Templates
Other Symbols (, %, #, ", ')

Signs and symbols should be used consistently within documents. The following rules are in effect:
Use the degree symbol () following a number to indicate temperature; use the word "degrees" for
measurement of angles.
The percent symbol (%) is used only in places where space is limited, such as tables or figures.
The word "percent" is always spelled out in text; use numerals with this word in all cases.
o Research has established that 49 percent of us are below average.
o "Half of baseball is 90 percent mental."Yogi Berra
3. Mechanics 43
The percent symbol (%) and the pound sign (#) are used as UNIX prompts. The percent symbol
indicates commands issued in the regular user shell, while the pound sign means that the command
is issued as the root user.
Use quotation marks (") to indicate inches in exact measurements; thus, it is always preceded by a
numeral. Spell out "inch" in compound modifiers (e.g., 9-inch nails) and approximate
measurements. If the " is the last thing in the sentence, the punctuation comes after it. There should
be no space between the number and the inch mark.
Use a straight single quote (') to indicate exact feet. Spell out "feet" in compound modifiers (e.g.,
the proverbial 10-foot pole) and in approximate measurements. If the ' is the last thing in the
sentence, the punctuation comes after it. There should be no space between the number and the foot
mark.
Compounds
A compound is written in one of three ways:
As one word
As two words
As two words joined by a hyphen (or in some cases, an en dashsee "En Dash ()," above)
Generallyand only generallythese rules are correct:

Compound nouns, if not mentioned in this style guide or in the Glossary, are open or closed
according to The Chicago Manual of Style. If it's not there, look in Webster's New Collegiate
Dictionary. If the word isn't listed anywhere, take a vote and add the result to the next edition of
the <!> Glossary and Acronym List.
Compound nouns formed from a verb and a preposition or particle are always closed.
o We hold out the BRM on first pass; a holdout
o The manager has to sign off on this work; her signoff
3. Mechanics 44
Compound verbs formed from a noun and a verb are hyphenated.

o I copy-edited the story.
o Deacon Jones was known for head-slapping the people that tried to block him.
o Exception: The USPS wants to barcode all mail.
When a noun and a verb ending in -ing act as a compound modifier before a noun, they are
generally not hyphenated:
o mail processing machine, mind altering substance, street fighting man
Adverbs ending in ly followed by a participle or adjective are not hyphenated.
o poorly dressed, highly controversial, newly released
Not all words that end in ly are adverbs; adjectives like early and friendly could take a
hyphen, as in "early-morning meeting."
Adjectival phrases in the form noun-adjective or noun-participle are hyphenated when they appear
before the noun being modified.
o labor-intensive process, first-pass holdout; user-friendly interface, multiple-delivery point
However, these same combinations are not hyphenated when they appear as predicate
adjectives or somewhere other than immediately before a noun.
o The computer is user friendly; The process is labor intensive; Hold out the rural carriers on
first pass
Compound adjectives wherein the several parts are in effect one unit of meaning, are hyphenated.
o three-quarters full, system-level failure, third-best time
Compounds involving numbers are hyphenated.
o 16-bit processing, 4GB hard drive, 256-color monitor, 10-inch screen
3. Mechanics 45
Certain prefixes are almost always closed. These are listed in Table Style-3; exceptions follow.
Table Style- 3. List of closed prefixes

Prefix Example
ante anteroom
anti antimatter, antivirus
bi bicycle, bipedal
bio biosphere
co codependent, coprocessor
counter counterofer, countermeasures
extra extracurricular
infra infrared
inter international
intra intranet
macro macroeconomics
meta metalanguage
micro microscope, microcosm
mid midlife, midline, midpoint
mini minivan
multi multiview
neo neonatal
non nonmachinable
over overbearing
post postwar, postdirectional
pre predirectional, pretest
pro pronoun
proto prototype
pseudo pseudoheroic
re reconnect, reedit
semi semiautomatic
socio sociolinguistic
sub subsection
super supercede
supra supranational
trans transoceanic
ultra ultrasound
un unmitigated
under underfunded
Exceptions to the entries in Table Style-3 include the following circumstances:

Capitalized words or numerals ("mid-August," "pre-1998")
Creating a word with the spelling of an existing word ("re-cover," meaning "to cover again," not
"to get better")
3. Mechanics 46
More than one word ("posthigh school"note the en dash)

Prefixes standing alone (The software contains both multi- and single-record displays.)
Repeated vowels other than e ("semi-independent," "co-opt," but "reengineer")
Acronyms ("nonDPS"note the en dash, required with all acronym and dash combinations)
Forms that might be confusing ("co-edition," because "coed" is another word)
The majority of compound and hyphenation decisions fall into the categories outlined in this
section. However, since The Chicago Manual of Style has a 12-page table on the subject, that book
is the official arbiter of such decisions. As always, the goal of any technical writing and editing is
clarity, and choices should be made with that in mind.
Spelling
The dictionary of choice is Merriam Webster's Collegiate Dictionary. That book is superceded
when the word is listed in the <!> Glossary and Acronym List, however.
Spellings for new applications should be decided on in cooperation with project managers and
developers. Add the new terms to the <!> Glossary and Acronym List when a decision has been
made.
Acronyms and Abbreviations

Because the language of technology is more precise and more repetitive than natural language,
using shortened forms of standard terms (or acronyms) can save space and reading time without
sacrificing clarity. Acronyms should be used thoughtfully and always with regard for the intended
reader. If a reader is not familiar with an acronym, those acronyms can turn a document into an
alphabet soup that is annoying and time consuming to interpret.
Definitions
An acronym is usually formed from the initial letters of a compound expression. It can be
pronounced as a word or pronounced letter by letter. Acronyms do not contain periods. Examples:
RBCSRemote Bar Coding System
DUCdelivery unit computer
Some acronyms have become regular English words. Some were formed from the initial letters and
syllables from a group of words, like:
Radarradio detection and ranging system
Other acronyms have been formed from the first and last syllables of a group of words:
Motelmotor hotel
Like "radar" and "motel," some acronyms are better known than the words they represent.
Examples include the following:
3. Mechanics 47
BASIC, a programming language, is commonly known by that name rather than "Beginner's All-
Purpose Symbolic Instruction Code."
FORTRAN originated as an abbreviation for "Formula Translation," but everybody knows it as
"FORTRAN."
No one knows what a Zone Improvement Program is, but they know what a ZIP Code is.
The <!> Glossary and Acronym List indicates which acronyms commonly used in our projects may
go exclusively by their letters rather than the words that the letters stand for.
Guidelines for Use

There are three ways acronyms are treated:
Type I: The most common way is that the acronym follows the definition the first time it is used,
assuming that the acronym will be used again in the document (short documents) or chapter (for
long documents). In this case, the acronym should never be used only onceit should be stated
only if it will appear again. For more information, see the rules below.
Type II: The second case of acronym usage involves those terms whose acronyms are better known
than the terms themselves. This is often true of application names and mail processing machines,
for example. These acronyms, which are marked in the <!> Glossary and Acronym List with an
asterisk, should be used after the first mention of the (spelled-out) term regardless of whether the
acronym is used again in the document or chapter.
Type III: The third way to use an acronym is by itself, without its spelled-out definition. This
applies to technical terms like CDROM, where the acronym means more than the words it
represents. These acronyms, marked in the <!> Glossary and Acronym List with a , are used
undefined and as acronyms on their first mention, even if it is the only mention.
Type I and II acronyms must be included in the list at the end of a document.
These rules apply to the use of Type I acronyms:
The first time a term with an acronym appears in the document, spell out the words. If the term is
used again later in the document, put the acronym in parentheses after the first use of the term. If
the spelled-out term is used only once in the document, do not use the acronym. An example
follows:
o The research was conducted at the United States Postal Service (USPS). The USPS randomly
selected 5,000 letters and sent them through various coding platforms.
3. Mechanics 48
These rules apply to all types of acronyms:

Do not assume that because a term has an acronym, it should be capitalized. Whether it can
become an acronym has nothing to do with capitalization of the underlying term. For rules on
capitalization, see "Capitalization," above or for capitalization of selected terms, see the <!>
Glossary and Acronym List.
o input subsystem (ISS)
o Our Better System (OBS)
Use the same acronym to represent a given meaning throughout a document.
Select an acronym's indefinite article based on the pronunciation of the first letter of the acronym
not on how the acronym may be pronounced as a word. Examples include:
o an AADC table
o an MLOCR, not a "muhlohcur"
When making an acronym plural, add a lowercase s. Do not use an apostrophe. Even when the
plural form of the written-out term would take an s somewhere other than at the end of the final
word, form the plural of the acronym by adding an s to the end.
o The plural of flat sorting machine (FSM) is "FSMs"not "FSM's."
o The plural of run batted in is written as "runs batted in." However, the plural acronym is
"RBIs."
Note Do not use a plural form of an acronym the first time the acronym appears
in a document. The plural form is not an accurate description of the
acronym.
Barcode readers (BCR) make mail delivery faster.
Use an apostrophe and s to indicate the possessive form of an acronym:
o the PDA's keying system
In the rare cases where an acronym is used as a verb, add d to indicate the past tense, or
ing to indicate the progressive:
o I FTPd the patch to Suburban.
o They are DPSing the mail.
Use an en dash instead of a hyphen between a word or a prefix and an acronym since the an
acronym represents several words.
o an EUwide program
If an acronym is generally pronounced as a word, you may include the pronunciation with the
acronym's entry in the glossary. An entry should look like this:
ASCII ("asky")Word commonly used for "American Standard Code for Information
Interchange," a programming language.
Other assorted acronym rules:
3. Mechanics 49
An acronym may be used in a heading, but do not spell out its meaning in the heading. Instead,
spell out the full term in the first sentence after the heading, unless it has been spelled out before in
the document or chapter.
Use the official Post Office abbreviations for states and address suffixes.
Use acronyms in tables or figures to save space as needed. Be sure to include those acronyms in the
document's acronym list.
Numbers and Numerals

The following rules apply to the use of number and numerals. A list of examples appears at the end
of this section in Table Style-4.
Generally, spell out numbers zero through nine unless the number proceeds a unit of measure. Use
numerals for numbers 10 and higher.
Measurements are generally expressed with numerals, even if the number is less than 10.
Measurement elements include: weight, length, bytes, point sizes, percent, money, number of digits,
and periods of time shorter than a day. References to the age of a person or object are also
considered units of measure, and are never spelled out.
o 6 inches
o 6 feet, 3 inches (or 6' 3")
o 1 byte
o a 1-year lease
For round numbers of 1 million or more, use a numeral followed by the word. Indefinite
amounts may be spelled out when they are figurative:
o thousands of reasons to leave
o $10 million
o a hundred screaming lunatics
Use numerals in compound modifiers if numerals would have been used of a noncompound form of
the phrase. Likewise, spell out numbers that would normally be spelled out.
o 1-minute delay
o three-dog night
o 2-inch connector
o 9-digit ZIP Code
Insert commas to break up numerals of 4 digits or more into 3-digit groups (e.g., 16,050 and
200,511). Do not use a space on either side of the comma. Note that years and ZIP Codes never
use commas.
If numbers (whether numerals or spelled out) are adjacent in a sentence they should be separated
by a comma.
o On July 12, 350 sites will receive the new software.
3. Mechanics 50
However, no comma is required if one number is expressed in numerals and the other is
spelled out. A comma would also be acceptable, though, in this example:
o On page 78 four modifications are listed.
A sentence should never start with a numeral or version number. If starting the sentence with a
numeral cannot be avoided, then spell out the number. Adding modifiers or rewording the sentence
can generally resolve this problem.
o Twelve sequences have been highlighted for the high-rise building.
Spell out the time of day in text except when hours and minutes are given or when used with "a.m."
or "p.m." In most every case use the 12-hour clock, including the minutes followed by a.m. or p.m.
Use "12 noon" and "12 midnight" to prevent confusion.
o The test will start at four this afternoon.
o The test will start at 4 p.m.
o The test will start at 4:23 a.m.
In text, covers, headers, footers, and other places, spell out the month, but use numerals for the day
and year. The month always precedes the day, which precedes the year.
With fractions, use numerals or words according to the rules above:
o We stayed for five and a half days.
o We slept for 5-1/2 hours.
o With the upgrade, the software will perform 3-1/2 times faster then previous versions.
The exception is a fraction before an "of" phrase. Always write out the fractions that
precede this prepositional phrase:
o three-quarters of an hour
Do not use endings like sts, ths, ds, or nds after fractions. (This is wrong: "12/22nds.")
Also, do not use the Word fraction characters; always use fractions with full-size numbers
and a full-size solidus.
Decimal fractions that are less than one should be written with a zero before the decimal point.
However, if documenting user input, do not add the zero if it is not necessary for the user to enter
it. If decimals are used in a table, align the decimal points in a column.
Always use numerals to describe percentage. Always spell out the word "percent," except in tables
where the symbol (%) may be used in tight spaces.
Ratios and proportions are always expressed as numerals. Use these forms to express a ratio:
o a ratio of 5 to 1
o a 5-to-1 ratio
Ordinal numbers place items in a sequence, such as first, second, and so on. Ordinal numbers
should always be spelled out in the text of a document and should not be used in dates. The ly
ending should not be used when using ordinal numbers.
o First, do no harm.
Roman numerals in lower case are used to number the pages of a document up to and including the
table of contents. All page numbers use numerals.
3. Mechanics 51
Other assorted rules that relate to the use of numbers and numerals are:
Bin or pocket numbersAlways use numerals, but do not include preceding zeroes. Always
lowercase the word bin with a numeral. Example: "bin 9"
Option numbersAlways use a numeral, followed by the name of the option in this format: "Select
Option 2, ZIP+4 Browser, from the main menu."
ZIP CodesZIP Codes are always numeric, obviously. Use hyphens (and no spaces) after the first
5 digits and after the next 4 digits (assuming that more numbers follow). Example: 22801-2332-
08.
Version numbersVersion numbers (always numeric) are preceded by the letter v, with no space
between the letter and the number. There is no need to ever write out the word "version" unless it is
a general reference, like "In this version of the software." Thus, a version number is always
stated like this: v7.4.
Table Style-4 gives examples using the rules stated in this section.
Table Style- 4. Examples of the use of numbers and numerals

Use Rather Than
10 ten
25 twenty-five
1,000 1 thousand
1,000 one thousand
300 3 hundred
300 three hundred
5 million five million
5 million 5,000,000
(703) 359-5779 (note area code in parentheses)
22030-4534-02 11-digit ZIP Code
step 5 step five
page 32 page thirty-two
Section 4 Section Four
415 Eckert Circle, Apt. 8
two days 2 days
2 hours two hours
I am 6 years old. I am six years old.
The 12-year-old computer The twelve-year old computer
4,589 4589
12,899 12899
v7.3 V.7.3; 7.3; v.7.3; version 7.3
4 p.m. 4:00 p.m.
four in the afternoon 4 in the afternoon
4:23 a.m. fourtwenty-three in the morning
July 27, 1999 27 July 99; 7/27/99, etc.
$14 million fourteen-million dollars
$10.5 billion 10 billion dollars
3. Mechanics 52
Use Rather Than

0.2 inches .2 inches
15 percent 15 %
9 percent nine percent
First step 1st step or One step
Twenty-second 22nd
October 23 October 23rd
First Firstly
nineteenth nervous breakdown 19th nervous breakdown
bin 9 Bin 009
References
Start a cross-reference by telling users why they should look elsewhere, not where they should
look, even if the reason is not specific. That is, use: "For more information about blah, see section
x." instead of: "See x for more information about blah."
Initial references to a figure or table should always come prior to the figure or table, as close to the
figure or table as is possible.
Note Whenever possible, use the Word cross-reference feature when referring to something in
the document. See "Cross-references," page 23.
Use the verb "see" rather than "refer to" when directing the reader to another portion of or item in
the document. It is shorter and it sounds less formal. For example:
See Chapter 4.
The Caption window contains several fields. (See Figure 4-1.)
If the parentheses immediately or within a word or two follow the item being referred to, you may
leave out "see."
Look through the list in the Contents window (Figure 2-1) and select the name that best matches
the installation being performed.
The caption window appears (Figure 4.1).
3. Mechanics 53
"See"-references should include the information listed in Table Style-5. Note the punctuation and
the inclusion or lack of page numbers. There is never a reason to include "in this document" or the
like after the referencethat part is understood.
Table Style- 5. "See" reference styles

Reference To Style
Numbered Heading 1 or 2, See Section 2.1. (non-user documents, where all the headings are
anywhere in the document numbered)
See Chapter 4. (user documents)
Or: See Section 2.1, "<Section title>."
Unnumbered Heading 2 or lower See "<Heading>" in Chapter 4.
in another chapter See "<Heading>," page 19.
Unnumbered Heading 2 or lower See "<Heading>," above/below.
in same chapter
Numbered Heading 3 or lower, See subsection 4.4.2.
anywhere in the document
Figure See Figure 9-1.
Table See Table 8-7.
Appendix See Appendix A.
Step See step 5 in "<Heading/section number>," page 34.
Use "above/below" rather than page number if the heading referred
to is in the same chapter or section as the reference.
Portions of other documents See (the) Title of Other Document, Chapter 4.
Or: See (the) Title of Other Document.
Do not use page, figure, or table numbers in references to other
documents.
Be sure to include the other document in the list of related
documents (usually Section 2), if there is one.
Not all references are "see" references, of course. If there is a way to incorporate the reference into
the regular flow of a sentence, do it. Remember that something is always "in" a figure or table
never "on" or "at" a figure or table. Here are some references made in the flow of the text:
How do I love thee? Table 2-1 counts the ways.
Employee birthdays and the dates on which cake will be served are listed in Table 10-4.
In Figure 3-2, the dark box represents either the vast emptiness of a life lived only for personal
gain or the network serveryou decide.
Figure 3-4 depicts the flow of bribe money from various cities to the members of the International
Olympic Committee.
3. Mechanics 54
Referenced Documents Lists

Any document referred to in the text should be listed in the "Related Documents" section of the
document, when there is one, in this style:
Document Title (Document Number).
Note the bullet, the italicized title, and the period at the end. In the document number, do not
include the version: for example: K-OGS75-SDP, rather than K-OGS75-SDP-004. You do not
want to have to update your list when new versions of other documents are released.
For non<Company_Name> documents, include the company or author and publication date if one
is available, like this:
Document Title (Author/Company, Date), <pages>.
Usage
This section covers a few general topics in writing and word usage. For the treatment of specific
words, terms, and phrases, see the <!> Glossary and Acronym List.
When Style and Screen Disagree

In an ideal world, programmers would have to follow document style guides, or at least submit
their screens to some sort of grammatical review. The fact that they do neither of these proves
(along with ample evidence from other areas of life) that we do not live in an ideal world. Thus,
there will always be cases where something in an application screen does not match the technical
writers' agreed-upon way of writing it.
As much as technical writers might hate it, it makes more sense to call a screen by the name the
programmer has given it, no matter how illiterate is sounds. It could be confusing to the reader to
find out that the ZIP+4 Search window on their computer is actually the same as the ZIP+4
Query/Edit screen they see mentioned in the manual. Likewise, don't change the words of an on-
screen message when reproducing them in a manual.
However, writers are allowed to improve upon the original screen presentation (including names
and messages) in the following categories:
CapitalizationYou must remember this: a "Zip" is just a "ZIP," a style is just a style. (The
fundamental things apply.) "bmc" should always be "BMC," "postnet" is always "POSTNET," and
so on.
SpellingInformation technology is so powerful now that people will accept spellings from any
computer screen rather than from an dictionary made of boring old paper. Just because it's
electronic doesn't mean it's spelled correctly. Never reproduce a misspelled term from the screen.
Punctuation (including hyphenation)For example, even if a programmer did manage to get a
hyphen into "MSC-only record," there's no way in hell she thought to put an en dash there. (It
might not even be possible in some operating systems.) However, the manual should use "MSC
only record" in all cases.
SpacingTech writers may add or eliminate spaces when necessary. For example, "IDTAG" on
the screen should become "ID Tag."
3. Mechanics 55
Inconsistent usageA main menu is best called a "main menu," rather than, for example, the Main
Menu Options screen. A sort program is always called a sort program, even when the application
says "sort plan."
When Writing Instructions

Generally, there are two types of writing in user documents: information and instruction.
Information is most often conveyed in "normal" paragraphs of two or more sentences. This could
includeamong other thingsdescriptions of applications or background system information.
The real meat of a user document, however, is the instructions. This is what a user picks up the
manual for (assuming, as we must, that he picks it up at all). Instructions tell how to accomplish a
task using the software: how to print a report, how to add a record, and so on.
Here are some things to keep in mind when writing instructions:
Small TopicsTackle only one task in a section. For example, don't explain how to open the
application, open the database, make changes, save the file, and print the report all in the same
section. Users are most likely interested in looking up only one task at a time, and the tasks are
easier to find if they each have their own heading. More headings make for more exact cross-
references and break up the pages of the manual for a cleaner look and easier reading.
Use NumberingThere is a style called Stepsuse it. Don't put a string of instructions in a
paragraph; put one or two instructions in each numbered step. It might take more room, but it's
easier to read, it makes the pages of the manual look better, and it's easier to follow for a user
keeping one hand on the page and one hand on the mouse.
No Tutorials Unless Clearly MarkedRecognize when you are writing instructions and when you
are writing a tutorial. Instructions tell how to do one task; tutorials show how to string a few tasks
together to accomplish a project. A manual may have instructions only, or it may have instructions
followed by a tutorial, but it should not have only a tutorial (unless there exists somewhere else a
book of instructions); nor should it include hybrid sections that are part tutorial, part instruction. If
you do include a tutorial, make sure the files referenced will be available to the user. Also, be sure
to call it a tutorial or example so the user recognizes that it is showing a single path through the
software rather than a complete set of situations and instructions.
It's Not a Continuing SagaNever assume, when beginning a section, that the user has just
completed the actions in the previous section. That is, the fact that things go in that order in the
manual does not mean that the user will do them all in that order. This means, for example, that
instructions for each section need to start at a logical place (the main menu, perhaps) rather than
starting wherever the previous set of instructions ended. A topic should never start out by
instructing the user to exit a menu or clear an option that was selected in the last topic.
3. Mechanics 56
Start With VerbsInstructions are most clear when you start them with a verb:
o Press Z.
o Click OK.
You can dispense with words that come before the verb, like "The user should" or
similar phrases. Another space-saving, clarity-enhancing device is to say the name of the
screen only once, or only when it initially appears (and again if it reappears after
disappearing). For example, the first action to be taken in a dialog box might read: In the
Print dialog box, select All. In the next step, don't mention the dialog box (assume that the
action should be taken in the same place as the last step): Click OK.
When saying that a window appears, put it at the end of the step that includes the action
that made it appear, rather than at the beginning of the next step. This allows you to start
the next step with an action rather than an explanation or set-up line.
One caveat to this ruleif writing a step that is optional, put the information describing
what the action does before telling the action. This helps the user decide whether she
wishes to perform the action. Example: "To format your hard drive, click OK" rather than
"Click OK to format your hard drive."
One Step for One ActionDon't pack several different actions into one numbered instruction. At
most, include a few closely related actions, like making a selection and pressing Enter.
Same Thing, Same WayVariety may be the spice of life, but it can be confusing in technical
writing. Try to write the same actions using the same wordsdon't try to be too creative with the
instructions. (Creative urges are best expressed in the information parts of the document.) Sounds
boring? It is boring. But there are places where boring is the right thing to be; instructions are one
such place.
Following the word usage rules in this style guide and in the Glossary and Acronym List
will limit your choices anyway. Just keep in mind that if the user reads the same instruction
written in two different ways, he may wonder whether the sentences describe the same
action. You don't want that.
Tell How To Work the Software, Not How the Software WorksRemember that in a user's guide,
you are talking to a usernot a programmer. While a programmer may really enjoy knowing about
algorithms and inline processing or whatever those things are called, the user in all likelihood is
physically unable to care less. So don't write like this:
o Activate the OK button. The application fetches all entered variables and runs an algorithm,
then calls the Results screen and displays the quotient of errors over mailpieces processed.
It's really a question of point of view and the old story about blind people touching
different parts of the same elephant. Things that have meaning for developers don't mean a
thing to users. The reader is trying to use the applicationnot analyze the code. The
reader is trying to work the applicationnot find out how the application works.
3. Mechanics 57
Table Style-6 shows some examples of what developers see and what users would rather
see.
Table Style- 6. Programmer's perspective vs. user's perspective

Programmer's Perspective User's Perspective
Causes a window to be displayed A window appears
Enables the user to Lets the user
The system displays a window... A window appears
The window is displayed... A window appears
Will bring up a window A window appears
The software goes through an algorithm to produce (Just say what the user sees next.)
Provides visibility into Shows; Illustrates
Power of the system Turn of the system; Restart the system
Press F5 to accept the data Press F5 to submit (or enter) the data
Tense
Write in the present tense as much as possible. Do not use the future aspect unless the action
spoken of is truly in the future. Do not use conditional structures unless there really is some doubt.
Do not make what should be the main verb into a gerund that becomes the subject of the sentence.
For example:
The File window appears.
Not: The File window will appear.
Not: The File window should appear.
Press Enter to open the File window.
Not: Pressing Enter will open the File window. (Verb as subject; also in future tense)
Not: Pressing Enter opens the File window. (Verb as subject)
If the file is not accepted, reenter the information.
Not: If the file is not accepted, you will have to reenter the information. (Incorrect use of a
future/conditional hybrid)
<Company_Name> will hire more people next year. (Proper use of future aspect)
Warning: The Delete All button will erase all of your documents. (Proper use of future)
We could hire more programmers, should the need arise. (Proper use of the conditional)
User's guides take the present tense almost exclusively. When you are describing different options
and their results, state the option, then proceed as if the user were definitely taking that path. In
other words, the fact that the user is not required to do the steps does not make them optional or
conditional on paper. For example:
There are two options on the Print screen:
Print Selected Files
Print All Files
To print only the selected files, press S. The Print Options window appears. Click OK.
(Not: To print only the selected files, you should press S)
3. Mechanics 58
Active vs. Passive Voice

In general, use the active voice. However, a few passive-voice sentences are not a high crime. In
fact, they can be used to vary the tone of a passage much like synonyms are used to diminish the
repetitive use of a word. Also, don't break your neck trying to assign an actor to a sentence that
doesn't need one. The Web site The Slot points out that there is nothing wrong with the sentence
The active voice is overrated and that it is superfluous to insert a semantically empty subject just
for the sake of having an actor: People overrate the active voice.
Another example is the contrast between The software was developed and Programmers
developed the software. Or between The mail is sorted according to ZIP Code and The postal
service sorts the mail according to ZIP Code. The subject in the active version is essentially
empty. The Slot says:
"If I want to report that the Powerball numbers will be drawn tonight, what exactly would
be the point of assigning that action to someone? 'A lottery official will draw the Powerball
numbers tonight'? 'Herbert J. Melton, 42, will draw the Powerball numbers tonight'?"
Of course, in most cases, the active voice is preferable. But the occasional passive sentence is not
necessarily bad.
Words To Mistrust
An authority no less than Ernest Hemingway instructed writers to "Mistrust adjectives." (Note that
he did not write "Mistrust those doggone, stinking adjectives." That would have been like that "I-
am-a-Cretan/All-Cretans-are-liars" thing.) And Hemingway was talking about writing fiction.
Imagine what he might have crossed out in a technical manual. Or, save your imagination and read
these examples of unnecessary adjectives:
The available functions include
a password entered by the individual station manager
Note that different alphabetic letters signify types of routes
Enter the desired number of copies
Adjectives like these add nothing to the sentence. You would not list the functions unless they were
available. The station manager is by definition an individual (a person, really) and thus the word is
useless. In the third example, 1) the same alphabetic letters wouldn't tell much, and 2) since there
are no numeric letters, the reader can be trusted to assume that all letters are alphabetic. Finally,
why would anyone enter a number of copies different than the one he or she wants? It's not that
these aren't valid words, but that they either add no meaning or they confuse the meaning. If a word
isn't doing honest work, delete it.
Be wary also of adjectives hiding in relative clauses, pretending to be relevant:
The functions that are available at the bottom of the screen include
The functions available at the bottom of the screen include
The information that is present on the screen
The information present on the screen
You can lose three useless words (from the full relative clause) with:
3. Mechanics 59
The functions at the bottom of the screen include

The information on the screen
Other candidates for summary deletion are adverbs:

Two sort programs can be merged together.
Highlight the record that is already marked.
Ask yourself whether "merged together" says more than "merged" or whether "already marked"
says more than "marked." Doubt any answer other than "no."
Second Person vs. Third Person

Exclusive use of the third person can get in the way of writing clear instructions; it seems that
when the third person is mandatory, more words are required to stay out of passive constructions
and logical fallacies. For this reason, use second person in user documentation.
Never mix second and third person. In this example, the first part of the phrase is in third person
and the second part is in second person (as the implied subject of "click" is "you"), and thus the
sentence has managed to refer to the same person from two different points of view:
If the user does not want to enter records, click Skip.
In nonuser documentation (requirements, software development documents, project plans, and
other technical documents), use the third person exclusively.
Phrases That Can Be Reduced

The best technical writing is concise. Reduce clauses to phrases and phrases to words wherever
you can. Table Style-7 lists some groups of words and shorter ways to replace them.
Table Style- 7. Phrases that can be reduced

Avoid Use
agree with the idea that agree that
any already existing files existing files
at the present time now
by means of by
by the use of with, using
check to ensure that check whether; ensure that
click on the Save button click Save
during the time that while
express a need for ask for
for the month of January for January
for the purpose of for, to
identifies the quantity of shows, tells, gives
if the events are such that if
in a similar fashion similarly
in conjunction with with, along with
3. Mechanics 60
Avoid Use
in order for for
in order to to
in the event of when, if
in the June to July time frame in June or July
in the neighborhood of about
in view of the fact that because
it can be seen that
it is apparent that apparently
it is assumed that (person) assumes that
it is proposed that (person) proposes that
it will be remembered that remember that
located near near
make an approximation as to how much estimate
merge together merge
numeric value number
on an as-required basis as required
on the order of about
point in time time
point to the Save button and click click Save
press the F3 key press F3
prior to before
provides the capability to allows (the user) to
See Section 3 in this document. See Section 3.
subsequent to after
would seem to suggest suggests
3. Mechanics 61
Words That May Not Be Used

For some words, like the ones in Table Style-8, there is little excuse. It's not their faultthey're
just drawn bad, to quote Jessica Rabbit. They should be burned up and never used again. As we
can't actually burn them, we will have to settle for not using themever. It would be very
gratifying to blame Microsoft for these, but the evidence is not strong enough to support a
successful prosecution.
Table Style- 8. Banned words

Banned Word Example Alternative
conference The managers conferenced regarding the The managers met regarding the issue.
(as verb) issue.
decline (As the opposite of increased): He declined Decreased, lowered, lessened
(as transitive verb his hours of sleep to have more hours
meaning "decrease") available for work.
desired Enter the desired number of copies. Enter the number of copies.
encaptured Our policies are encaptured in this set of This is apparently a combination of the
principles. dumb business/technology overuse of
captured and the important-sounding
encasulated, made to rhyme with
enraptured, which is what whoever uses
this word probably is in relation to his or
her own prose. Anything is better.
hit Hit Enter. Press Enter.
interface Interface with the customer and see what Meet with the customer
(nontechnical use) they have to say.
liaise Liaise with the customer representative to Meet with the representative
finalize the requirements.
matrix (as verb) Matrix the data by type and amount. Organize the data...
particular Format the particular word as you like. Format the word as you like.
In this particular case. In this case.
please To save the file, please click Save. Be more rude: To save the file, click Save.
progress We hope to progress the work beyond the We hope to make progress, we hope to
(as transitive verb) initial stages this week. advance the project
provide visibility into The user interface provides visibility into There may be nothing stupider than this
the data collection process and results. phrase. First of all, visibility means the
ability to be seen. It doesn't go with into at
all. Neither does provide. And why would
anyone provide it when all that needs to
be done is "let the user see" or something
like that?
simply, just To print a report, simply press; It is insulting to the user to assume that
To enter the data, just any of this is simple:
"To print a report, press"
"To enter data,"
sited Be sure the monitor is properly sited. located, placed
3. Mechanics 62
Banned Word Example Alternative

sortation Mail sortation is carried out 24 hours a Mail is sorted 24 hours a day.
day.
special The software has a special feature that Special to whom? Another way to think
organizes the data. about it: each feature is equally "special,"
so why trumpet this one? Delete it.
status The team leader expects each member of The team leader expects each member to
(as transitive verb) the group to status his or her work daily. report daily on the status of his or her
work.
surface In need of advice, the programmer The programmer discussed the problem
(as transitive verb) surfaced the issue with his supervisor. with his supervisor.
task (as verb) Task the tech writers with formatting the Assign tech writers to format the
document. document.
They are tasked with writing requirements. They are writing requirements.
utilize The development efort utilizes object- There was nothing wrong with "use."
oriented design principles.
For a list of verbs that should not be used in instructions related to software, see the <!> Glossary
and Acronym List.
Formatting
This section applies to the formatting of words or phrases, rather than to the paragraphs treated
with standard styles.
Bold
In general, boldface the object of a verb in an instructional passage. Do not boldface the subject of
a sentence (e.g., "F14" in the third bullet below) or the object of a preposition (e.g., "File" in the
first phrase of the fourth example below), even when it is the name of a window, menu, field, or
other screen item. Some examples are shown here:
Select the Spaces checkbox.
Click Open.
F14 opens the report generation utility.
In the File field, enter a file name.
Do not boldface a pronoun or article unless it is part of the name of an option, as in this example:
OK: Find the file, then select it.
Better: Select the file.
The word "Note" is bold when used in a notebox.
Punctuation is generally bolded only when the words on both sides of it are both bold. An exception
is quotation marks, which are bold at both the beginning and end of a bold phrase (if they are
necessary).
The headings in a table are bold, and titles down to level 3 are also bold.
3. Mechanics 63
Finally, do not use bold type for emphasis; rather, use italics.
Italics
Quotations from an application screen should be in italics. This applies mainly to prompts and
other messagesnot to field names, options names, and the like. For example:
When the cursor is in the Directional field, a message appears at the bottom of the screen: Enter N
S W E NE NW SE or SW.
Document names and the names of Internet sites (the titlenot the URL) are in italics.
Use italics to emphasize important words like "not" or "with" without which the meaning of the
sentence would be altered or diametrically opposed to that which was intended. The following
example might even call for more than a single italic word, but alas, provisions for that have not
been made in this style guide.
When looking into an empty gas tank, do not use a match to help you see the fuel.
This style guide is unusual among technical documents in that it has many occasions to give
examples of words and sentences. Generally, in this document, words used as words are in
quotation marks, while single letters used as letters are italicized. Sentences used as examples are
italicized unless they are in a bullet. Though other documents will not have nearly as many chances
to use these rules, do italicize single letters used as letters and continue to place words used as
words in quotation marks. For example:
Separate the As from the Ds.
That depends on what the meaning of "is" is.
Online Help Rules

Applications used to create online Help systems come with their own set of default type styles. Use
those styles rather than translating our document styles into the application. However, word usage
and other style rules still apply. The rules for bolding and italicizing also apply, but may be
interpreted loosely.
Keep in mind that Help systems are nearly as much about graphical presentation as they are about
writing (and this means, of course, that you pay more attention to graphic designnot that you
slight the writing), and thus if it makes the page or the instruction more clear to bold phrases that
you would not bold in a document, go ahead. You may also want to use more bullets, shorter
sentences, and shorter sections than you would in a regular manual. Above all, make things easy to
find; make sure that all the links and bells and whistles work; and make sure that even an eye
accustomed to the written page can find what it needs to find in relatively short measure.
For obvious reasons, don't include in the online Help topics such as logging on or installing the
software. If they can read the Help, they have already done this. Information on how to open the
online Help would not be particularly useful, either. Also, use fewer screen shots in online help, as
the user is able to see both the screen and the instructions for its use. A screen shot can even be
confused with the real screen, if it's large enough.
3. Mechanics 64
Appendix A. Section 508 Information
This appendix describes various aspects of documents and help systems that make them Section
508 compliant.
Alt Text
A descriptive text equivalent must be provided for every non-text elementprimarily images. The
alternative text should succinctly describe the purpose of each non-text element.
To add alt text to images in Word documents:
1. Right-click an image and select Properties. The Format Picture box opens.
Alternatively, you can double-click the image.
2. Click the Web tab and in the Alternative text box, begin by typing Figure: Then finish entering the
description.
3. Click OK.
After this, screen readers will read, and Adobe Acrobat will display, the description.
For information about adding alternative text for images in RoboHelp, see "Making RoboHelp
HTML Output 508 Compliant."
Simple Tables
Tables of data can be difficult to interpret if a person is using a non-visual means of accessing it.
Screen-reader users can easily get "lost" inside a table because it may be impossible to associate a
cell that a screen-reader is reading with the corresponding column headings and row names. To aid
these users, keep tables simple. Primarily, this means not merging cells.
In addition to the above recommendation, there are tags for tables in the HTML code in a
RoboHelp online help system. For details, see "Coding Tables with Proper HTML Tags."
Making PDF Files 508 Compliant

It is easy to make PDF files 508 compliant. This is done by turning on a feature in Acrobat called
tagging. This gives each paragraph and heading a unique ID and allows screen readers to more
easily read and navigate through the file. Unfortunately, creating a tagged PDF takes a lot of time.
Because of this, create a tagged PDF only for the final release of a document destined for the
USPS.

Before generating the final PDF, ensure that the tagging is turned on. To do this:
1. Select the Adobe PDF menu, then choose Change Conversion Settings. The Acrobat PDFMaker
box opens.
2. On the Settings tab, select the Enable accessibility and reflow with Tagged PDF check box (see
Figure B-1).
Figure B-1. Enabling PDF tagging
If that checkbox is selected, at the time you are generating a PDF for a large document, the prompt
may appear giving you the chance to turn off tagging. Click No.
Making RoboHelp HTML Output 508 Compliant

The following items will ensure that an online help system generated by RoboHelp is Section 508
compliant:
Adding alt text for images and hyperlinks
Adding document links (or D-links) for complex images
Coding tables with proper tags
Turning on the 508 setting for output generation
These are explained in the sections that follow.
Adding Alt Text for Images and Hyperlinks

Add alternative text for both images and hyperlinks. To add alt text for images in RoboHelp:
1. Double-click the image. The Image box appears.
2. In the Screen Tip field, type the alternative text describing what the figure is illustrating.
3. Click OK.
A. Section 508 Information 66

To add alt text for hyperlinks in RoboHelp:

1. Double-click the hyperlink. The Hyperlink box appears.
2. In the Screen Tip text field, type the alternative text describing the topic that is linked to. (This is
often the same as the display text of the link itself.)
3. Click OK.
Adding Document Links (D-Links) for Complex Images

Complex graphics and charts may require a more detailed description than can be provided in an
alt tag. If the information cannot be provided in the body of the page, a document link, or d-link,
should be available directly beside or beneath the non-text element. A d-link is a text hyperlink to a
file that provides the information displayed by the chart or image.
Example:
<img src=chart1.gif alt=Figure 1: Chart title=Figure 1: Chart>
<a href=www.companyname.com/chart1.htm alt=Figure 1 description
title=Figure 1 description>D</a>
Coding Tables with Proper HTML Tags

If a data table has one logical level of row or column headers, it is a simple table. We recommend
using the table header <TH> tag and the id and header attributes. The id attribute within the
<TH> tag is used in the first cell of each column to define the column header. The id attribute
within the table data <TD> tag is used in the first cell of each row to define the row header. The
header attribute within the <TD> tag of all other cells is used to associate the cell with its
corresponding row and column headers. A sample of a properly coded table is below.
Example of a Simple Table (Using the header and id Attributes)
The code for this table immediately follows the example.
HTML code for the table above:

<table width = 66% border = 1 summary = "This table summarizes the rates for
Priority Mail Global Guaranteed postage rates.">
<caption> Rate Table for Priority Mail Global Guaranteed</caption>
<tr>
<th id= "header1"> Weight not over (lbs)</th>
<th id= "header2"> Rate Groups 1 and 2</th>
<th id= "header5"> Rate Group 5</th>
<th id= "header6"> Rate Group 8</th>

</tr>
<tr>
<td id= "row1"><center>0.5</center></td>
<td header= "row1 header2"><center> $20.00</center></td>
</tr>
...and so on.
Turning On the 508 Setting for Output Generation

To ensure that RoboHelp's output for WebHelp (HTML-based online help) is Section 508
compliant:
1. On the Projects tab, expand the Single Source Layouts item.
2. Right-click WebHelp (Primary Layout) and select Properties. The WebHelp GeneralWebHelp
box appears (Figure B-2).
Figure B-2. Enabling 508 Compliant Output for WebHelp
3. Select the Section 508 Compliant Output checkbox.

4. Click Next to continue to additional settings, or click Save.
Checklists
To ensure that Word documents and online help systems comply with Section 508, use the
following checklists.

Word Documents
Alt text has been provided for all images
Tables are simple, with no cells spanning multiple columns or rows
Tagging was turned on prior to PDF file creation
RoboHelp Generated Online Help

Alt text has been provided for all images
Alt text has been provided for all hyperlinks
Document links (or D-links) have been added for complex images
Tables are simple, with no cells spanning multiple columns or rows
Tables have been coded with proper <th> tags for header rows and <td> tags for regular rows
(using the TrueCode tab)
The Section 508 Compliant Output setting was selected prior to generating the output

Company_Name> Style Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Company_Name> Style Guide

Uploaded by

Copyright:

Available Formats

<Company_Name> Document Style

Prepared for: Prepared by:

Find Replace With: Example

Document Style Guide i

Creating Notes With AutoText.......................................................................................................18

Appendix A. Section 508 Information.....................................................................................................65

Table of Contents iii

Why a Style Guide?

"God is in the details."

Document Style Guide 1

Relationship Between Type Styles and Form

<Company_Name> Document Style Guide 3

The Standard Template

Table Document Structure- 1. Standard styles

Style Name Definition Where Used

Style Name Definition Where Used

Attaching Templates and Importing Styles

Microsoft Word Settings

Straight Quotes, Ordinal Indicators, and Fractions

Sections of the Standard Template

Figure Document Structure-1 shows how it works.

Figure Document Structure- 1. Cover setup and styles

For in-house documents, use this disclaimer:

Description Author Version Date

Table of Contents and Lists of Figures and Tables

Body of the Document

Figure Document Structure- 4. Sample glossary entry

The variables in this format stand for the following information:

Names of Electronic Document Files

<Company_Name> Document Style Guide 15

Headers and Footers

Figure Mechanics- 5. Headers and footers

Setting Up Footers to Change at Each Section

The text in both columns is Normal style.

Creating Notes With AutoText

To use the AutoText entry:

Alternately, if you like using the mouse, you can do this:

Adding Graphics to a Document

To insert a Visio diagram:

Figure Mechanics- 6. Caption box

2. The Caption box is used for all kinds of labels.

Include chapter numberCheckbox is selected

Figure Mechanics- 7. Cross-reference box

Complying With Section 508

Classes of words that are capitalized include:

<Company_Name> Document Style Guide 26

Table Style- 2. Words not usually capitalized

Capitalization of Hyphenated Words in Titles

Capitalization in Tables and Graphics

Capitalization in Proper Nouns

Names of calendar divisions

Capitalization in Program and Project Names

Capitalization in Acronyms and Abbreviations

The plural marker (s) on an acronym is in lowercase. For example:

Capitalization in Computer Terms

Screen Items and Choices

Use of All Caps

Angle Brackets (< >)

Apostrophe and Possessives (')

Do not use an apostrophe when adding a suffix to an acronym. For example:

Use an apostrophe followed by an s in possessive indefinite or impersonal pronouns. For example:

"The staff reached a conclusion" becomes "The staff's reaching a conclusion"

Multiple objects or predicates relating to only one subject do not require a