Writing an Excellent Procedure

Why This Matters

Complete, yet concise, procedures aid the folks using those procedures by helping them accomplish the task successfully the first time.

What You Do

Folks who are trying to follow procedures are typically looking for a way to do things or following a documented process to ensure that all steps are followed in sequence and without missing steps. Keeping those things in mind, these perspectives help make that better:

1. Make the procedure as simple as possible for the person reading the procedure.
2. Provide the reader with the critical information necessary for success.
3. Respect the reader's time by making the collection of procedures consistent in layout and writing style. When all of the procedures have the same general layout, the reader understands more easily quickly finding information, both in the overall set of documentation and in a specific procedure.

How You Accomplish It

Use this simple and yet effective procedure layout.

What this is

In a single sentence, explain to the reader what this procedure will accomplish.

This section facilitates the concept of "fail fast": the faster that the reader can determine that this procedure is the wrong procedure, the more quickly they can find the proper procedure.

What you need to have

This is the first of the two sections of prerequisites.

List the things that you need to actually have in order to perform the procedure successfully. The typical categories of things that go here are:

• URLs to external web sites,
• Software you need to have installed and configured,
• Security aspects, which include things like
• Membership in certain domain roles or other security groups,
• Processing account names and passwords for any machines or servers involved (refer to the account name type, but omit all account names and passwords from this public info.)
• Include the Servers Index if the work needs to happen on any servers.
  • As a sub-item, include a table with the list of servers.

What you need to know

This second sections of prerequisites contains the caveats--the "gotchas" that need to be known before doing the procedure.

List the topics and skills that the person running the procedure needs to know in order to run it successfully and avoid potential issues, such as:

• How to do any specialized functions in the software listed in "What you need to have";
• When you can and cannot run the procedure because of business rules or environmental constraints.

What you need to do

Now that you have given the reader the preliminary information, this is where you give them the step-by-step items of the procedure. Writing a good procedure follows a concept of functional decomposition. A key point is to keep the instructions at any level consistent with the other instructions at the same level.

Some Background

As you can tell by the content references above, this best practice was developed in the software support business. Writing operational information technology (IT) procedures has worked this way across multiple groups at multiple organizations, both in the private and public sector, for more than 17 years.