Example Instructions 1: WS-FTP Pro—Annotations

Instructor note. Provide some information as to the audience and situation of your instructions—explain what assumptions you are making about your audience's knowledge, background, skills.

Titles. Normally, you'll want how to or -ing phrasing for the title of instructions. This title does not clearly indicate that instructions are going to provided.

Audience. The audience is quietly indicated by the fact that readers must have an Internet account (which implies a number of things about their level of knowledge) and have some familiarity with Windows.

Overview. In an introduction to instructions, it's a good idea to provide readers with an overview of the tasks and concepts about to be covered—which these instructions fail to do. A simple overview might save something like "The following instructions explain what WS-FTP is, how to configure it, how to connect to a site, how to upload and download files, and how to create directories."

Background. In some cases, instructions must provide some background on the tool to be used (as is the case with WS-FTP here), the processes to be formed, or the concepts behind the instructions. In a way, this section does provide the overview mentioned as lacking in the preceding section.

Heading structure. Notice very carefully what is going on with the headings in these instructions. The specific tasks—such as configuring, connecting, uploading, downloading, and so on—are subheadings (third-level headings) to the higher-level heading ("How to Use WS-FTP Pro," a second-level heading). That's because this writer wants the task sections not to be confused with the concept section (the section on WS-FTP in general).

Second-level headings. Notice that these instructions have two second-level headings, highlighted in red. They are like the roman sections of an outline. (We don't use first-level headings because the document is relatively brief.)

Third-level headings. Notice the third-level headings in these instructions—they are "run into" the paragraphs they introduce. They are like the capital letters that provide second-level detail in traditional outlines. (Notice too that all the third-level headings are parallel in phrasing. That is, they all use the how/what/when/where/why phrasing, rather than gerunds (ing) or noun ohrases.)

Numbered steps. In instructions, you present each step that the reader must take in a separately numbered-list item. Notice the format: a number, a period and then a space before the text; no parentheses. Notice that the "run-over" lines align to the text of the item, not the number.

List lead-ins. Introduce every list you have in a document with a lead-in, which need not be a full sentence as some of the examples in these instructions show. Notice that the lead-in is punctuated with a colon.

Imperative writing style. Notice how the individual steps here use the imperative style of phrasing (open this, aim that, click this, and so on). This is standard with instruction-writing. "You" is also commonly used. The idea is to get the reader's full attention. (Not all imperatives are shown in red in the example.)

Special notices. Most instructions include special notices: notes, warnings, cautions, and danger notices, usually accompanied by special formatting. No special notices are included here though. If you are familiar with an FTP tool like this one, you might think for a moment about the various "gotchas" that can occur: for example, accidentally erasing files or sending binary files as plain-text (ASCII) files. good instruction writing warns readers of the common mistakes that can be made.

Highlighting. these instructions use a fairly common style of highlighting found in computer documentation. Bold is used for button or menu names: when you click on them, it's like issuing a command. Courier New (a typewriter-style font) is used for text the user must type in, displayed messages, or examples. Italics is used when you want to indicate something the user must substitute for, such as filename. (Not all of the items that use highlighting are shown in red in the example.)