ITS 3250 - Securing Systems

Security Strategies Wherever We Can Find Some...
Lesson 13-14

This lesson reviews encryption, which we covered in the Windows text, chapter 4, and returns to the original text on Windows for some ideas about Standard Operating Policy (SOP) documents. Objectives:

• (see lesson 3 in this course)
  
  
• Definition of instructions
• Legal issues
• Organizing the material
• Notes, precautions, cautions, warnings, and danger
• List of tools and materials
• Chronological order
• Command voice
  

Definition of instructions

Sets of instructions are the most common kind of technical writing. Instructions are defined as a chronological set of steps in a procedure. They are not always numbered steps, but numbering the steps is highly recommended. Instructions are contrasted with process analyses: instructions use active voice to tell a reader how to do something, while a process analysis describes what other people do and what the results may be. Process analyses may be more like telling a story about people and events, while instructions tend to be more like a series of commands.

Legal issues

Good instructions provide some measure of protection from lawsuits. Instructions should include appropriate warnings about the potential danger a product may present when used improperly.

Organizing the material

The usual recommendations about determining the level of instruction your audience requires apply to procedures. Instructions become very unclear when the writer assumes knowledge that the user does not have. When in doubt, explain more rather than less. Use clear organization to make it easier for a knowledgeable user to skim over familiar material.

As noted above, it is recommended to number the steps in a set of instructions. A simple numbered list is sufficient in many cases. When the instructions are complex, a standard outline structure is recommended. Here are four structures that are recommended as being the "most reliable": 

• Arabic/Letters - Arabic numbers are used for each section, and letters are used for subsections
• Digit-dot-digit Decimal System - Sections are numbered with successive Arabic numbers, a dot and a zero (e.g. 1.0). Subsections will have the same number as their parent section, and change the zero to successive numbers (e.g. 1.1, 1.2, 1.3). If subsections need further division, more dots and numbers are added (e.g. 1.1.1, 1.1.2, 1.1.3). This system is clear, but can be hard to follow if the numbers are too long. Also, some users are confused if a section has ten subsections. They may wonder if 1.1 is the same subsection as 1.10.
• Digit-dot-zero-digit Decimal System - Like the system above, but subsections are given leading zeros (e.g. 1.01, 1.02). This avoids some confusion that can be found in the system above: 1.01 and 1.10 are visually different enough to avoid confusion. A drawback may be that the writer should determine the complexity of the outline first, to determine how many leading zeros are needed. The same number of leading zeros should be used in each case for consistency.
• Digit-dash-digit System - A variation on the first decimal system that uses dashes instead of dots (e.g. 1-1, 1-2, 1-3). In this variation, the author starts with 1-1 instead of 1-0, which is why it is not a decimal system. Either variation of this method can be correct, as long as the writer is consistent. For some people, this one is more readable.
  

Notes, precautions, cautions, warnings, and danger

Some organizations may use a system of five levels of alerts for the reader. The levels below are presented as a suggestion. The definitions used for the alerts are not universal. Defining these levels for the user may avoid misunderstanding of the intensity and importance of the message.

• Notes - additional information that may be helpful to the user following the instructions
• Precautions - alerts to possible problems that may be avoided with the information provided; may reference avoiding minor damage to property or equipment
• Cautions - alerts to possible damage to property
• Warnings - alerts about possible health and safety issues
• Danger statements - alerts about possible risk of loss of life

In addition to this graduated scale of alerts, it is recommended that you associate a visual identifier with each of them, so they will be readily recognized in your documentation.

List of tools and materials

When working with hardware, a list of tools and materials needed to carry out the instructions is expected, and should precede the instructions themselves. In the case of unusual or specialized equipment, illustrations are recommended to make the list clear. If, for example, the reader must obtain a specific part to repair a device, a picture of the part, the part number, and a recommended supplier may all need to be provided. Video of an installation may help enormously.

Chronological order

When describing a mechanism, the technical writer has some choices in the order of presentation of material. When writing instructions, the steps must be put in chronological order: the order in which they are to be carried out. Instructions written in any other order will be confusing at best, and may cause the reader to damage equipment, or suffer injury.

Command voice

Instructions are written as commands. They must be clear, detailed, and sequential. Use parallel constructions where possible, to improve instructions. For example, this one does not use parallel construction:

1. Remove the access panel.
2. Remove the retaining screws.
3. The fuser may now be removed.

In the example above, the third instruction uses passive voice, and does not deliver on the reader's expectation of a simple instruction. A better way to write this:

1. Remove the printer's rear access panel.
2. Remove the fuser's retaining screws.
3. Remove the fuser from the printer.

This set of instructions uses the same (parallel) word pattern three times. It also includes a reference to the location of the parts to remove. Illustrations of the actions would make the instructions better than just text.