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:
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.
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).
Use as a verb only when you are describing reading data from storage or writing data to storage.
AIFull caps. Abbreviation for Artificial Intelligence. Spell out on first occurrence in a major section, and then use 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/orNot acceptable. Avoid using and/or by rewriting the sentence.
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.
back up (v.)
Two words as verb.
One word as noun and adjective.
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).
Boolean operatorsInitial cap B when referring to Boolean. Use all caps for the Boolean operators AND, OR.
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.
CD (n.)Use instead of compact disk. Plural is CDs.
Avoid this auxiliary verb because it implies uncertainty on the part of the writer. Use can instead.
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.
Avoid using this term. Describe items that are gray on menus and in dialog boxes as not available, unavailable, or shaded.
Avoid using disable as a verb in user documentation. Use the phrase make unavailable about commands. Acceptable in developer documentation.
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.
Not acceptable in reference to information documented earlier. Use a cross-reference to that material.
Earlier is the correct term in the context of product version numbers. Don't use lower in this context.
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.
input (adj., n.)
Don't use input as a verb. Use enter instead.
Not left-hand. Upper left and lower left are acceptable (hyphenate them when you use them as adjectives).
Avoid using a string of nouns (a noun gang) as a modifier. Noun gangs force the reader to work too hard to comprehend text.
Use prepositions with elements of the user interface
as specified in this entry of the Style Guide.
willThe word will places an action in the future. Use the future tense only when it is necessary.
Correct© 2002 Autodesk, Inc. All Rights Reserved.