Writing Procedures

This page provides guidance for writing procedures.

Every set of procedures has four elements: a title or heading, an introduction, the step-by-step procedures, and an end point.

Titles and headings

The title or heading should briefly explain what the procedure will accomplish.

Use the bare infinitive to form titles or headings for a set of procedures. Avoid using the -ing form of a verb, either a gerund or the present participle.

Use sentence case for section headings and page titles.

Introduction

The introduction provides preliminary information that a user needs in order to follow a set of procedures.

Each introduction will be unique, but may contain the following information:

Why a task should be completed.
It may not be clear why a user should perform a set of procedures. If it’s not clear, explain what the benefit is or what the outcome will be.
When a task should be completed.
Are there routine tasks that should be completed on regular basis? For example, performing a system backup or certificate rotation. Should a set of procedures be performed after another event? For example, after a software upgrade.
What safety measures should be completed before starting a set of procedures.
Do they need to back up data before they start a set of procedures? Is there a security risk?
How long will it take to complete a set of procedures.
This is particularly important if a set of procedures will take a long time to complete. If users will spend several hours completing a task, they need to know in advance. This is also important if users have critical systems that might be down for an extended period of time.

Prerequisites

A set or procedures may require certain hardware or software, or certain permissions or access to complete a set of procedures. Include those requirements before a set of procedures.

If users will install third-party software, include links the system requirement documentation for that software.

Writing steps

Procedure levels

Procedures should be written at the highest level that the user will understand.

The lowest level of a set of procedures might tell a user to enter their username, then enter their password, then click on the Sign In button. A higher level would tell users to log into an account. Both of these levels achieve the same goal, logging a user into an account, but the lower level splits the procedure into several smaller steps. This lower level is too low for must users and certainly too low for Chef’s users.

Higher level tasks give the user a better overview of the procedures and where they are while following a set of procedures. Higher level tasks are also less likely to become obsolete when a product is updated.

It’s important to understand the users’ skill level so steps can be written at the correct level.

Each step is an action

Each step is an action that a user will perform or a decision that a user must make. If an action triggers a response from an application or a system, that response is not a step.

Use an imperative verb in the first sentence of every step to clarify the action that the user will take. Format each step as a separate ordered list item.

Components in a step

Many steps only require a description of the action that a user will take. However, users may require additional information to complete or understand a step.

Use the following order to describe each component of a step:

Describe the action that the user will take.
Show the command they will run or the text they will add or update, if necessary.
Explain any placeholders in the command, if necessary.
Explain the command in detail, if necessary.
Show the command output, if necessary.
In a separate paragraph, explain the significance of the output, if necessary.

For example:

Restart the service on the Chef Infra Server.
```
chef-server-ctl restart <SERVICE_NAME>
```
Replace <SERVICE_NAME> with the name of the service you are restarting.
The chef-server-ctl restart subcommand restarts all services on the Chef Infra Server or a single service if you specify a service name.
When the service restarts, it returns:
```
ok: run: service_name: (pid 12345) 1s
```
The output above shows that the service has restarted correctly.

If possible, group long sets of steps into multiple groups.

It can be mind numbing for a user to go from one step to another to another over a long set of procedures without an ending point. Group long sets of procedures into subgroups. This adds a functional level that keeps users oriented as they complete each set of tasks.

Optional steps

Preface optional instructions with Optional: before each step.

Conditional steps

Preface conditional steps with the condition.

Conditional steps should begin with If. Users rarely read ahead when reading a set of instructions, so if the condition is placed at the end of a step, they may perform the action before realizing that it doesn’t apply to them.

Single-step procedures

Use an unordered list item for single-step procedures.

End point

Every set of procedures has an end point, which is the state of a system after completing a set of procedures. This may be a midway point in a long set of procedures, or the conclusion of a set of procedures.

When a user reaches an end point, they should intuitively know or be able to verify that they’ve reached the end point. If it’s not clear, include a picture of a user interface, a CLI output, a command that a user can run to verify that a system or application is running, or the description of a file detailing its completed state.

General guidelines

Test procedures

Test procedures from beginning to end while writing them.

It’s difficult to evaluate the quality of a set of instruction unless you run through them and perform the tasks while you’re writing them. Someone else should also test the procedures after they’re written. This could be another writer, someone in customer support, or potentially a customer.

Use the imperative mood or indicative mood

Write all instructions using the imperative or indicative moods.

The imperative mood tells the user to do something.

The indicative mood states facts.

Avoid passive voice

Passive voice is often vague and it can be unclear who or what is performing an action.

Don’t use should

Don’t use the words should, could, and would. They create ambiguity and could cause confusion over whether you’re making a recommendation or stating a requirement. If you write, “You should back up the server,” is that a requirement or a suggestion?

If a user must perform a task, use must.

If something will happen as the result of a user action, don’t use should, just say what will happen.

Don’t use please

We’re not trying to win an etiquette contest. Just tell the user what to do in simple clear text.

Don’t use we when referring to the user

We are not doing anything. The user is doing something so use you if you must, but it’s better to use the implied you in the imperative mood .

You is better, but try to avoid it if possible.

If this is a step that the user must perform, try using the imperative mood . It’s simpler, shorter, and more direct.

Use an ordered list to document steps

Use an ordered list to document steps. The exception is if there is only one step in a set of procedures.

Note

Hugo automatically renders an ordered list in Markdown into the correct numerical order in HTML, so all you have to do is preface each step with 1.. This makes it easier to add, reorder, or delete steps later. For example:

1. The first step.
1. The second step.
1. The third step.

produces:

The first step.
The second step.
The third step.

Avoid using the phrase “Run the following command”

Focus on what the user is doing, then show the command that the user will execute in a code example.

Present tense

In general, you can omit the word will and use the present tense rather than the future tense to describe user actions and system responses. Users perform actions in real time as they read through the instructions, so from the user’s perspective, actions and system responses happen in the present.

Reserve the future tense and will for events that happen in the future from the user’s perspective.