Writing Effective Procedures | Patricia McPhee Portfolio

Clear, concise procedures reduce errors and help users complete tasks without confusion.

Start with an action verb

Begin each step with a direct action verb. Users immediately know what action to take, which reduces hesitation and confusion.

Correct

Install the latest version of Docker.
Deploy the latest build:
```
kubectl apply -f deployment.yaml
```

Incorrect

The latest version of Docker needs to be installed. Select here to install.
You should deploy the latest build using kubectl apply -f deployment.yaml.

Be clear and direct

Specificity removes ambiguity. Each instruction should clearly define what action to take, where to perform it, and why.

Correct

Navigate to the /var/logs directory to review the server logs.

Incorrect

Check the server logs.

Limit each step to one action

Each step should focus on a single task. Users are less likely to make mistakes when steps don't combine multiple actions.

Correct

Select File > New Project to create a new workspace.
Select File > Open.
Select Options > Preferences.

Incorrect

A new workspace is created by going to the File menu and selecting New Project.
Select File, open it, and adjust your settings.
Go to Options, select Preferences, and adjust your settings.

Include expected results within the same step

Include the expected result immediately after the action. Users confirm they're on the right track without leaving the step.

Correct

Select Refresh to update the page. The latest data appears.
Select Start to begin the process. A green status light indicates it's working.

Incorrect

Select Refresh. You will see the latest data on the page.
Select Start. The machine will start working (indicated by a green light).

Why the incorrect examples fail

Both incorrect steps use future tense ("will see," "will start") to describe system behavior. Use present tense instead.

Use simple, accessible language

Avoid jargon or overly technical terms unless necessary. When you must use a technical term, define it on first use.

Correct

Use the slider to adjust the volume.
Select Connect to start the connection.

Incorrect

Manipulate the audio output level with the slider control interface.
Initiate the process of establishing a connection by selecting the Connect button.

Avoid using "please"

Starting with "Please" makes the instruction sound passive and less direct, and often unnecessary. In technical environments, clarity and precision are valued more than politeness.

Correct

Enter the component name.

Why this is better: This version is straightforward and removes unnecessary formality. It gets to the point and respects the user's time.

Incorrect

Please enter the name of the component.

Be specific, not generic

Generic descriptions like "the name of XYZ" do not provide meaningful guidance. Descriptions should indicate what the user needs to input or select.

Correct

Enter a unique name for the microservice, for example, 'payment-service'.

Why this is better: This version provides context ("unique name") and an example, making it easier for the user to understand what is expected.

Incorrect

The name of XYZ.

Provide context where necessary

Offering context helps users understand the purpose of a step, especially when the step requires a decision. Keep added context under 150 words. For longer explanations, use a separate section.

Context empowers users with knowledge, leading to more informed actions and a deeper understanding of the process.

Correct

Restart your system to apply the changes after updating the software.

Restarting ensures all components of the software update are fully integrated and any in-memory data is refreshed.

Incorrect

Update the software and then restart your system.

Incorporate helpful visuals

Use screenshots or diagrams to support complex steps or software navigation. Avoid adding images that don't directly support the instruction.

Visual aids reduce cognitive load. Too many visuals clutter the documentation and dilute their impact.

Correct

In the Settings window, select the Advanced tab.

[Image of the Settings window with the Advanced tab highlighted]

Incorrect

Go to the settings and then find the right tab for more options.

No visual is provided, leaving users to guess which tab to select.