Skip to main content

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.

Recommend
Recommend
Not Recommended
Not Recommended

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.

Recommend
Recommend
Not Recommended

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:

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

For example:

  1. 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.

Not Recommended
Recommend

Optional steps

Preface optional instructions with Optional: before each step.

Recommend

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.

Not Recommended
Recommend

Single-step procedures

Use an unordered list item for single-step procedures.

Recommend
Not Recommended
Not Recommended
Not Recommended

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.

Recommend

The indicative mood states facts.

Recommend

Avoid passive voice

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

Not Recommended
Not Recommended
Recommend

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?

Not Recommended
Not Recommended
Recommend

If a user must perform a task, use must.

Recommend

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

Not Recommended
Recommend

Don’t use please

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

Not Recommended
Recommend

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 .

Not Recommended

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

Recommend

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

Recommend

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.

Not Recommended
Recommend

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:

  1. The first step.
  2. The second step.
  3. 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.

Not Recommended
Not Recommended
Recommend

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.

Not Recommended
Recommend

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

Recommend
Edit this page on GitHub

Thank you for your feedback!

×









Search Results