Selected entries from: The AutoCAD Documentation Style Guide

Handout distributed by Virginia Rich at the May 16, 2002 forumon When the Word, Phrase and Even the Sentence Are Not Quite Right

Writers and editors of software documentation face a different set of headaches. If you've ever wondered about that haunted look in the eyes of a technical editor, glance through these Style Guide entries. Here are some of the things we have to be concerned about:

• avoiding technical jargon in material meant for users (see access, disable)
• using consistent language in books written by many writers (see prepositions)
• for clarity, using the same word for the same thing-no variety for the sake of variety (see press)
• using terms that make sense when the same material is used in printed books and in the Help system (see following)
• adhering to legal guidelines for trademarks (don't even ask me)
• using the second person and the present tense (see will)
• avoiding words and phrases that are difficult to translate (no contractions, no obvious idioms)

And we do sometimes indulge our general crankiness: see allow and let and appear.

There are also formatting issues; for example, we enforce a rigidly consistent list style and require headings at each level to have the same syntax.

above

Don't use when you mean higher on a page or earlier in a document or a section. Instead of using above, you can use a cross-reference to material shown earlier. You can also use the words previous or preceding (but only as documented in their respective Style Guide entries).

Correct
See the procedure in the previous section, "Setting the Time-Out Value for Devices." [FrameMaker cross-reference; no page number necessary.] The previous illustration in this section. . .

Incorrect
The illustration above shows you . . . .

access (v.)

Use as a verb only when you are describing reading data from storage or writing data to storage.

Correct
To access the new file, change to your home directory.

Incorrect
To access the Multiline Text Editor dialog box, use the Draw menu.

AI

allow and let

Avoid these verbs in the sense of a program or a command permitting or enabling a user to perform an action. Prefer using you can, or start sentences like this: With AutoCAD, you can . . . , or Using Multiline Text, you can. . . .

and/or

appear (v.)

Avoid this verb for information that is displayed on the screen, such as a dialog box or a message window. Use is displayed instead. Use for transitory information such as Quick Help and messages on the command line.

Correct
The Save As dialog box is displayed.
Blips are temporary markers that appear in the drawing area when you select objects or locations.
When you move your cursor over the main window, Help text appears at the bottom of the screen.

Incorrect
The Save As dialog box appears.

back up (v.)

Two words as verb.

Correct
When you back up your work, you won't lose it.

One word as noun and adjective.

Correct
Store the backups in a safe place. Use the backup file to restore your work.

below

Don't use when you mean lower on a page or later in a document or a Help topic. Instead of using below, you can use a cross-reference to material shown later, or you can use a more general statement, such as in the example or in the illustration. You can also use the words following or next (but only as documented in their respective Style Guide entries).

Correct
See the procedure in the following section, "Setting the Time-Out Value for Devices." [FrameMaker cross-reference; no page number necessary.]
The next table in this section . . . .
In the illustration, AutoCAD adds the dimensions you specified.

Incorrect
The illustration below shows you . . . .

Boolean operators

box

Avoid this term (if possible) to describe user-entry areas in dialog boxes; however, prefer using box to field if you must specify the user interface element.

can vs. may

Use the verb can when you describe actions that the user is able to do. Use may only in describing possibility or when an action's result is unknown or variable. Don't use may to imply that the user has permission to do something.

Correct
You may want to save your work before continuing. You can set a snap interval to force the crosshairs to jump or "snap" to that interval.

Incorrect
As you draw, you may enter a coordinate to locate a point.

CD (n.)

Correct
The sample drawings are on the AutoCAD CD.

could

Avoid this auxiliary verb because it implies uncertainty on the part of the writer. Use can instead.

Correct
A composite tolerance can specify both the diameter of the pattern of holes and the diameter of each individual hole.

Incorrect
A composite tolerance could specify both the diameter of the pattern of holes and the diameter of each individual hole.

default (adj., n.)

Use as an adjective or a noun, not as a verb. Carefully define what the default is at the first occurrence. Don't use default inside angle brackets in prompts.

Correct
If you don't enter a parameter, AutoCAD applies the default, which is the parameter in effect when you start the program.

dimmed

Avoid using this term. Describe items that are gray on menus and in dialog boxes as not available, unavailable, or shaded.

disable

Avoid using disable as a verb in user documentation. Use the phrase make unavailable about commands. Acceptable in developer documentation.

Correct
If a tile or an area is invalid or irrelevant given the current option settings, disable it immediately so that the tile or area is shaded and the user can't select it.

display (v.)

The verb display must always have an object. It is acceptable to use the passive form of this verb in the context of user interface elements.

Correct
The Insert dialog box is displayed.

Incorrect
The Insert dialog box displays.

earlier

Not acceptable in reference to information documented earlier. Use a cross-reference to that material.

Correct
See the procedure in "Setting the Time-Out Value for Devices" on page 234.

Incorrect
The procedure shown earlier on page 234.

Earlier is the correct term in the context of product version numbers. Don't use lower in this context.

Correct
AutoCAD Release 12 or earlier

following

Except as an introduction to lists, avoid this word as much as possible because it doesn't transfer to Help topics; instead, use a cross-reference to material shown later, or use a more general statement, such as in the example or in the illustration. Acceptable to use the phrase the following illustration only if the illustration appears under the same section heading as the text or in the same Help topic. Not acceptable to use the phrase the following section except accompanied by a cross reference. Never use below.

Correct
. . . as shown in the illustrations in "Calculating the Area Enclosed by an Object" on page 191.
In the illustration shown, AutoCAD adds the dimensions you specified.
... as discussed in the following section, "Calculating the Area Enclosed by an Object"

Incorrect
. . . as shown in the illustrations in the following section . . . as shown in the illustrations below AutoCAD draws a line using Ortho mode, as shown below.

input (adj., n.)

Don't use input as a verb. Use enter instead.

Correct
Enter the file name at the prompt.

left

Not left-hand. Upper left and lower left are acceptable (hyphenate them when you use them as adjectives).

Correct
upper-left corner of the screen
the line on the lower left

noun gangs

Avoid using a string of nouns (a noun gang) as a modifier. Noun gangs force the reader to work too hard to comprehend text.

Incorrect
the machined surface of the transmission case input shaft quill that contacts. . .

prepositions

Use prepositions with elements of the user interface as specified in this entry of the Style Guide.

In
Use in for dialog boxes, windows, lists, boxes for text, the drawing area, illustrations for the documentation, and so on.

Correct
In the Drawing Aids dialog box, . . .
in the Image Properties window
. . . all of the objects in the Available Objects list

On
Use on for tabs, the command line, a toolbar, the status bar, and so on. Use on for menus in procedures that document new features or in procedures that are being updated. (See the Style Guide entry standard wording in procedures for details about recent changes in our wording for procedures.)

Correct
On the command line, enter plinegen.
Click a button on a toolbar.
AutoCAD displays the current cursor location as a coordinate on the status bar.
On the Draw menu, click Arc.

Under
Use under for names of boxed areas in dialog boxes.

Correct
To add a word, enter it under Custom Dictionary Words.

At
Use at for prompts, including the Command prompt.

Correct
Enter all at the Select Objects prompt.

Into
Use into for dragging something into AutoCAD or into a drawing.

Correct
inserting a block into a drawing

Onto
Use onto for dragging something onto a toolbar.

Correct
dragging an icon onto a toolbar

press (v.)
Use press, not hit, to instruct users to use one keystroke that initiates an action.

Correct
Press the SPACEBAR.

will

Correct
The preliminary layout often contains HVAC objects that are connected by drawing ductwork.

Incorrect
Most often, when you draw ductwork you will be connecting other HVAC objects that have already been placed in the preliminary layout.

Return to When the Word, Phrase and Even the Sentence Are Not Quite Right