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 title case for page headings.
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.
Select Submit.
A dialog box opens with a “Success” message.
- Select Submit and a dialog box opens with a “Success” message.
- Select Submit.
- A dialog box opens with a “Success” message.
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.
Group related actions
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.
Update the config.toml
file to configure the node.
- Do the first thing to configure the server
- Do the second thing to configure the server
- Do the third thing to configure the server
- Do the fourth thing to configure the node
- Do the fifth thing to configure the node
- Do the sixth thing to configure the node
- Do the seventh thing to configure the node
Update the config.toml
file to configure the node.
- Configure the server.
- Do the first thing
- Do the second thing
- Do the third thing
- Configure the node.
- Do the first thing
- Do the second thing
- Do the third thing
- Do the fourth thing
Optional steps
Preface optional instructions with Optional: before each step.
- Optional: Override any default build phases you need using callbacks.
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.
- Reindex all organizations if the test is successful.
- If the test is successful, reindex all organizations.
Single-step procedures
Use an unordered list item for single-step procedures.
- To cleanse the node, run
chef-backend-ctl cleanse
.
To cleanse the node, run this command:
chef-backend-ctl cleanse
Cleanse the node.
chef-backend-ctl cleanse
To cleanse the node, run this command:
chef-backend-ctl cleanse
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.
- Check the system status.
- Back up the data.
- Check the system status.
- Back up the data.
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.
Run the following command.
chef-backend-ctl backup
Run the
chef-backend-ctl backup
command.chef-backend-ctl backup
Back up the data on the node.
chef-backend-ctl backup
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.