Obviously, writing technical material requires more than correct spelling. This section covers specifics of writing instructional text for computer-based tutorials. As you will see, certain devices are used to make information stand out more clearly. This is key, since proper emphasis will ultimately make your multimedia program easier to follow. Consistency is also important, because you want to create a consistent set of rules (and environment) for your users.

This section has four parts. Subject Material pertains to the subject (such as a device or program) for which you're writing instructions. Native Items deals with items (buttons, text) that are part of your tutorial, not related to the subject. Relevant Grammatical Rules touches on a few important guidelines. Computer Procedures examines instructions for specific computer procedures.

The Subject of the Tutorial

This part specifically examines conventions I have used for tutorials dealing with computer programs. The use of italics and other types of emphasis will work for other subjects as well. When writing about these other kinds of topics, use what works best for you, but above all, keep your usage consistent.

Write file format names in uppercase letters:

GIF
JPEG
MIDI
WAV

Use quotation marks with button names. Capitalize button names:

Click the “OK” button.
Click the “Print” button.

Use quotation marks with command names. Command names should appear exactly as they do on screen:

Select “Print...” from the pull-down menu.

Italicize menu names:

Select “New” from the File menu.

When a sentence ends with a menu name followed by an ellipsis, the ellipsis also serves as the period:

When you are finished, select “Print...”

Capitalize window names:

The Program Manager window.
The Main window.

Capitalize applications:

The Calculator.
The File Manager.
Close the Write window.

Capitalize icon names:

The File Manager icon.
The Control Panel icon.

Capitalize dialog box names:

The Save dialog box appears.

Use quotation marks with text box or field names:

The “Name” text box.

All letters in keyboard button names are upper case:

Press ENTER.
Press the DOWN ARROW key.
Press and hold down the ALT key.

Native Items

Do not use quotation marks with buttons unique to your program. These names should be lowercase:

Click the forward button.
Click the lesson menu button.

Specific items often need to stand out from any surrounding text. In these cases, it is acceptable to use quotation marks, bold or italic text, or another font to highlight an item:

Select “asparagus.doc.”
Select asparagus.doc.
Select asparagus.doc.

Choose your own style, but use a consistent method throughout the program.

Instruction text should look the same as the on-screen text it refers to:

Enter your password in the “PASSWORD:” field.
Select the “Text & Graph” layout.

When instructing a user to enter text, the specified text should appear in bold. Do not use a period if it can be misconstrued as part of the entry:

Enter 35 in the text box.
Type Richard Nixon
Enter http://www.atomicmartinis.com/

To differentiate actions the user must perform from other text, display on-screen action commands in red:

Press the ENTER key now.
Type: I'm the king of the world, woo!

Relevant Grammatical Rules

On the first reference, put technical terms in italics:

A fax/modem allows you to access on-line services.

When writing a sentence with three or more listed items, insert a comma before the conjunction:

Parsley, sage, rosemary, and thyme.

Generally, punctuation has the same formatting as the item preceding it:

It's on the left, not the right.
CD: a compact disc.

Letters and numbers used to enumerate vertical lists have a period:

1.
B.

Items in a vertical list do not end with a period, unless they are part of a complete sentence:

U.S. Presidents:
1. Washington
2. Adams
3. Jefferson

If part of a complete sentence, begin items with lowercase letters. Do not use a final period unless the items in the list are separated by commas or semicolons:

Do not attempt to fly unless
A. you have a plane;
B. you have wings.

Periods and commas go inside quotation marks:

Select “Save.”
These commands include “Cut,” “Copy,” and “Paste.”

Computer Procedures

In order to write about an operation or procedure, you must be able to explain it clearly. This section examines a variety of computer functions and how to describe them, displaying the logical progression required in instructional writing. Even in nonlinear programs, you'll need to delineate the processes the user must follow.

The mouse (or trackball, etc.) controls the position of the pointer:

Move the mouse pointer.

Click your left mouse button once to select an item.
Double-click your left mouse button to choose (or activate) an item.

The insertion point shows your position in a document. You can use your mouse pointer to place the insertion point in another location.

A list box displays a list of choices. A drop-down list box appears when you click the down arrow to the right of a selection box.

Select an item from a menu:

Select “Print...” from the File menu.
Select “Spelling” from the Edit menu. Select “Thesaurus” from the cascading menu.

If a menu command is dimmed in gray, you cannot select it.

An ellipsis following a menu command indicates a dialog box will appear when you select the command. Likewise, a button containing an ellipsis will open a dialog box.

A check mark appears to the right of some commands after you select them. This indicates the command is in effect.

A key combination following a command (such as CTRL Z) indicates a shortcut you can use instead of selecting the command. Simply type the key combination to perform the command.

A triangle to the right of a command indicates a cascading menu will appear when you move your pointer over the command.

List boxes display a list of choices. A drop-down list box appears as a rectangular box displaying the current selection. Selecting the down arrow at the right of the box displays a list of available choices.

You type information into a text box. Name it after the title that appears in front of it (i.e., the “Password” text box). Some text boxes are named after the dialog box they appear within.