Writing about Procedures: Review

As mentioned in the schedule page, you may not have covered these topics in previous technical-writing classes. They are essential for writing user guides, instructions, and all manner of procedures that resemble the style and format used in technical publications. These guidelines are requirements for the writing projects you do in this course.

These are minimal guidelines—don't feel restricted in livening up the look of your procedures, trying out format and style that you see in published procedures.

Titles

If your procedures, user guides, and other writing projects contain instructional material, the titles should use task-oriented phrasing. Instead of a title like Adobe Captivate, prefer something like Adobe Captivate: Quick-Start Guide, Adobe Captivate: Getting Start or Adobe Captivate: How to Create a Simple Tutorial.

Headings

The guidelines for task-oriented titles applies to task-oriented headings within a document. While you should try making headings in a procedure parallel in phrasing, it's impractical for the headings that introduce material not about tasks, for example, Adobe Captivate: New Features.

For brief procedures, no need for a heading like Introduction beneath the title and before the first paragraph. It ought to be obvious that the material following a title is introductory in nature.

Other heading guidelines such as those about lone headings, stacked headings, vague headings, accurate headings, pronoun reference to headings, and heading parallelism can be found at headings.

Introduction

The introduction to a procedure should in some way include the following elements, not necessarily in this order:

Usually, you can cover these elements quickly and in combination so that your introduction is not be more than 5 sentences. See in the introductions in the examples at the end of this page.

Bulleted, Numbered, and Nested Lists

Pay careful attention to the following:

These guidelines are presented in lists.

Illustrations (Figures) and Tables

Typically, figure titles (captions) are not needed in procedures because the illustrations are so localized to individual steps. Some procedures have descriptive titles but without the Figure x part.

If you do use figure titles, remember that figure titles go beneath the figure and must include a descriptive title. For example, Figure 3 is not adequate; Figure 3. Adobe Captivate main menu is.

Title for tables go above tables and, as with figures, should include a descriptive title along with the Table x part.

Text in figures and tables should be no larger than the standard body text.

Notices

Notices are those specially formatted alerts, cautions, dangers, warning, and notes. Pay careful attention to how notices are indented in relation to numbered or bulleted list items.

See notices for basic guidelines. If you want to use a different system, get in touch with your instructor.

Highlighting

Highlighting refers to any combination of bold, italics, color, alternate font, or capitalization.

See highlighting for basic guidelines. If you want to use a different system, get in touch with your instructor.

Writing Style

Procedures, at least in the US, use imperative voice for direct instructions: for example, Type your last name in the blank and press Enter.

Typically, additional explanatory material after a direct instruction uses "you."

In the introduction, you may have to refer to the audience as advanced users, for example, to establish who they should be. Thereafter, however, you can refer to them as "you" and use imperatives.

Avoid the telegraphic writing style (omission of "understood" words such as articles).

Example Procedures

You can see examples of procedures that follow most of these guidelines:

Examples.

Information and programs provided by hcexres@prismnet.com.