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

acronyms—with indefinite articles

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

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

Use .5 pt. lines for callouts.

capitalization—in lists

Capitalize the first word in each list item.

capitalization—in captions

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

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

Use sentence style (initial cap first word only).

capitalization—of window parts

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

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

Avoid “humanizing” machine interactions.

Problem: The machine remembers your choices.

Example: The machine stores your choices.

Courier font

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

Example: To start the IOT server, type the following command:

RUNiot_Server <em>pathname</em>

ellipses in GUI objects

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

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

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

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

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

Replace with present tense when possible.

gender

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

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

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

keystrokes

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

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

noun strings

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

Place only with the sentence part it modifies.

parentheses

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

Avoid passive voice.

possessive form of noun ending in s

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

Punctuation that follows an emphasized item is also emphasized.

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

punctuation in figure captions

Use no punctuation at the end of the caption.

punctuation in lists

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

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

Describe selections in the order the user makes them.

Example: Select the File menu, then Open.

serial comma

Precede the final “and” in a series with a comma.

Example: breakfast, lunch, and dinner

slash (/)

No space before or after a slash.

space after periods

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

split infinitive

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

tables, placement

Hang tables from a blank tiny or anchor paragraph.

trademarks

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…