Have questions about the tech writing process? Check out:
Technical Writing 101

Mechanics

acronyms

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)...

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

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.

Use .5 pt. lines for callouts.

Capitalize the first word in each list item.

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.

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.

Use sentence style (initial cap first word only).

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.

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

Avoid "humanizing" machine interactions.

Problem: The machine remembers your choices.

Example: The machine stores your choices.

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

RUNiot_Server pathname

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.

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.

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

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.

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.

Replace with present tense when possible.

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.

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

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

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.

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

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

Place only with the sentence part it modifies.

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).

Avoid passive voice.

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 that follows an emphasized item is also emphasized.

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

Use no punctuation at the end of the caption.

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.

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.

Describe selections in the order the user makes them.

Example: Select the File menu, then Open.

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

Example: breakfast, lunch, and dinner

No space before or after a slash.

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

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

Hang tables from a blank tiny or anchor paragraph.

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...

Scriptorium Publishing | Post Office Box 12761 Research Triangle Park, NC 27709 | (919) 481 2701 | info@scriptorium.com