7. Constructing Text
Typographic conventions help a reader distinguish special uses of words. When you select typographic conventions for computer documentation, you have some decisions to make. These decisions are dependent upon the type of hardware or software that you are documenting.
Make sure that you consider these factors when selecting conventions:
- A set of conventions already may be specified and used as a standard within the computer industry for your type of document.
For example, documents about hardware or software that is compatible with Macintosh systems often follow conventions defined by Apple Computer, Inc.
- If you design a unique set of conventions, make sure that the type is easily recognized and understood by readers, and that you explain how the conventions are used in the document.
Assigning Conventions to Text
There are no right or wrong typographic conventions, unless the type you choose is illegible or you mix too many fonts on a page. Most typography errors occur when writers do not apply conventions consistently. Here are some elements used in computer documentation for which you may want to establish type conventions:
- File names, directory names, path names, commands, and variables
- Generic classes of file names; for example, UNIX swap files or make files
- Menu names and menu commands in a graphical user interface
- Text you want the user to type
- Menu names and menu commands in a TTY interface
- New terms, emphasized words, and foreign terms
Working With Conventions
To help readers understand the typographic conventions you use in a document, explain and demonstrate the type conventions in the preface.
For example, if you do not need to specify many conventions for your document, you could format the explanation in the preface this way.
This book uses the following type conventions:
- New terms and book titles appear in italic type.
- Text that you type, when shown alongside an example of computer output, is shown in bold Courier font.
- Text that appears on the screen, such as a computer response or a file name, is shown in Courier font.
- Names of keys on the keyboard appear with initial capitals, such as the Return key.
- Two key names joined with a hyphen are simultaneous keystrokes. Press down the first key while you type the second character, as in "press Stop-a."
- Two key names joined with a plus sign are consecutive keystrokes. Press down the first key, release it, then type the second character, as in "press F4+q."
You could also present a more formal explanation of text conventions in a table format.