Standards home

Technical Writing 101: A Real-World Guide to Planning and Writing Technical Documentation

acronyms

acronyms with a(n)

bold type

callouts

capitalization in lists

capitalization in captions

capitalization in headings

capitalization in table titles

capitalization of window parts

compound words

computers are not people

Courier font

ellipses in GUI objects

em dash

en dash

figures, introducing

figures, placement

future tense

gender

indexing

italic type

keystrokes

Latin abbreviations

noun strings

only placement

parentheses

passive voice

possessive form of noun
ending in s

procedures, introducing

punctuation after emphasis

punctuation in captions

punctuation in lists

punctuation in quotes

selection, describing

serial comma

slash (/)

space after periods

split infinitive

tables, placement

trademarks

acronyms      back to top

Avoid excessive use of acronyms.

In each chapter, introduce every acronym by writing out the full wording and putting the abbreviation in parentheses. Thereafter, use only the acronym.

Example: The graphical user interface (GUI)...

acronyms—with indefinite articles     back to top

The article used (a or an) depends on the usual pronunciation of the acronym.

Examples: a North Carolina State University professor, an NCSU professor, a NATO treaty

bold type     back to top

Generally, use bold type for the names of things that users can select.

Buttons

Select the Add button.

Check box names

Check the Not Available check box.

Folder tabs

In your work folder, select the Available tab.

Icons

Select the Normal Work Dispatcher icon.

Key names

Select the appropriate skill, and press Enter.

Menus (except desktop menu)

Select the Tools menu.

Menu choices

Select the File menu, then Print.

Named items in list boxes or drop-down lists

From the Batch list box, select Batch 347.

The following items are not bold; however, they are capitalized according to how they appear in the software:

• Window titles
• Field names
• Pane names
• Application names
• List box names
• Drop-down list box names

Exception: desktop menu (not capitalized, not bold)    

Do not use bold for callouts when pointing out selectable items in figures.

callouts     back to top

Use .5 pt. lines for callouts.

capitalization—in lists     back to top

Capitalize the first word in each list item.

capitalization—in captions     back to top

Use sentence style (initial cap first word only).

For window titles, match capitalization in the software. Do not capitalize the word window.

Example: The Open File window is displayed.

capitalization—in headings     back to top

Use initial capitalization for every word in the book title, except prepositions, articles, and conjunctions.

Use sentence style (initial cap first word only) for all other headings.

capitalization—in table titles     back to top

Use sentence style (initial cap first word only).

capitalization—of window parts     back to top

Match capitalization in the software. Do not capitalize words such as field, tab, pane, button, list box, and window.

Example: The Personal tab is displayed.

Do not capitalize window classes or window types.

Example: A warning window is displayed.

Always use OK for the button on the GUI.

Always use ID as the abbreviation for identification.

compound words     back to top

Use a hyphen to form compound words. Exception: Use the en dash in compounds when combining open compounds. (See en dash for examples.)

computers are not people     back to top

Avoid "humanizing" machine interactions.

Problem: The machine remembers your choices.

Example: The machine stores your choices.

Courier font     back to top

Use Courier font to highlight what the user types. Use italic Courier to show variable information typed by the user.

RUNiot_Server pathname

ellipses in GUI objects     back to top

When describing a part of the GUI, omit any ellipses. If, for example, the File menu has an "Open..." choice, describe it as the Open choice in your document.

em dash     back to top

Use for a break in thought or abrupt change in sentence structure. See also parentheses.

Do not put spaces before or after the em dash.

Example: The snow—always welcomed by children—clogged the roads.

en dash     back to top

Use the en dash to connect dates, times, and numbers. Use the hyphen for compound adjectives. Use the en dash in compounds only when combining open compounds.

Examples: 1989–1995, the North Carolina–Virginia border

figures, introducing     back to top

Always precede a figure with a reference to the figure by number.

The Location window is displayed (Figure 2-5).
The figure follows and shows the window you are describing.

The Location window is displayed (Figure 2-5 on page 2-10).
The figure is located elsewhere in the document. Adding the page number to the reference is not necessary if the figure falls on the same or facing page as the reference.

The status bar in the Location window shows this information (see Figure 2-5).
The figure shows the Location window with the information you are describing.

The Location window, shown in Figure 2-5, has three sections.
The figure follows and shows the window you are describing.

Search the Last Name field to display an alphabetical list of clients, as shown in Figure 2-5.
Figure 2-5 shows the alphabetical list after the search.

figures, placement     back to top

Anchored frames should hang off a blank anchor or tiny paragraph. (Ask the template designer to create one of these formats if your project's template doesn't have either of them.) Shrink wrap the anchored frame around the graphic (Esc m p). Be sure the frame's Anchoring Position is set to Below Current Line.

future tense     back to top

Replace with present tense when possible.

gender     back to top

Use plurals or specific descriptions to avoid he, she, he or she, s/he, and it. See the example below.

Problem: The programmer writes code. He then compiles it.

Example: The programmer writes code and then compiles it.
OR: Programmers write code. They then compile it.

indexing     back to top

No initial capitalization unless it's a proper name.

Use gerunds whenever possible.

Use singular for nouns.

Collapse similar entries with secondary entries:

planting

bulbs

shrubs

trees

Instead of:

planting bulbs
planting shrubs
planting trees

italic type     back to top

Generally, use italic type for emphasis. Some docs also use italic type for placeholders.

keystrokes     back to top

Use a hyphen to connect keystrokes that are performed simultaneously.

Example: Ctrl-D [press the Ctrl key and the D key simultaneously]

Use a space to separate keystrokes that are pressed in sequence.

Example: Press Ctrl-M N to display the New window.

Latin abbreviations     back to top

Use the English equivalents. See e.g., etc., and i.e.

noun strings     back to top

Avoid noun strings. If you have one, hyphenate the words that are used as adjectives to aid comprehension.
Note: Never use a hyphen after an adverb ending in -ly.

Example: UNIX-based workstation, end-user access, newly acquired software

only placement     back to top

Place only with the sentence part it modifies.

parentheses     back to top

Use for tangential material. If the material is crucial to the sentences, parentheses are inappropriate. See also em dash.

Example: All students are required to study calculus (offered by the mathematics department).

passive voice     back to top

Avoid passive voice.

possessive form of noun ending in s     back to top

If a singular noun ends with an s, create the possessive form by adding 's.

Example: Dr. Seuss's books

procedures, introducing

Use a complete sentence ending with a colon, and follow the same grammatical pattern for all introductions in a document.

Example: To print the document, follow these steps:

punctuation after emphasis     back to top

Punctuation that follows an emphasized item is also emphasized.

Example: Press Ctrl-D, then press Ctrl-S.

punctuation in figure captions     back to top

Use no punctuation at the end of the caption.

punctuation in lists     back to top

Default punctuation: None.

If one item is a complete sentence that stands alone, put a period at the end of every item in that list.

punctuation in quotes     back to top

Periods and commas go inside the quotes unless the quote is something that the user types. Other punctuation is placed with the clause it modifies.

selection, describing     back to top

Describe selections in the order the user makes them.

Example: Select the File menu, then Open.

serial comma     back to top

Precede the final "and" in a series with a comma.

Example: breakfast, lunch, and dinner

slash (/)     back to top

No space before or after a slash.

space after periods     back to top

Use one space after a period. FrameMaker's Smart Spaces feature will prevent you from typing multiple spaces.

split infinitive     back to top

Avoid split infinitives, but do not mutilate your sentence to remove a split infinitive.

tables, placement     back to top

Hang tables from a blank tiny or anchor paragraph.

trademarks     back to top

Use trademarked terms as adjectives, not nouns. Mark the first instance of a trademark in the front matter and in the body of the document. Omit the trademark symbol in subsequent mentions.

Example: The Widget (TM) product offers... never Widget offers...