Skip to main content

Writing Effective Procedures

Last updated on
Open a doc issue   |   Edit this page

Clear, concise, and user-friendly procedures are vital for effective technical documentation.

It's often a challenge for engineers to transform their deep technical knowledge into accessible instructions. By applying clarity and simplicity, technical documentation becomes more user-friendly and easier to navigate. These improvements enhance the user experience and help reduce common errors that arise from unclear or poorly structured instructions, underscoring the crucial role of engineers in this process.

Start with an action verb

Begin each step with a direct action verb to make instructions clear and easy to follow. This format allows users to know immediately what they need to do.

Why it matters: Users quickly understand what action they should take, reducing hesitation and confusion. It also ensures that your documentation is task-oriented, which is easier for users to follow.

Correct

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

Incorrect

  1. The latest version of Docker needs to be installed. Click here to install.
  1. 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 the user must take, where to perform it, and why.

Why it matters: Clear instructions minimize the risk of errors and increase efficiency. Users should not have to guess what you mean; instead, your documentation should be precise.

Correct

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

Incorrect

  1. Check the server logs.

Limit each step to one action

Each step should focus on a single, manageable task. This makes complex procedures easier to follow and helps prevent confusion when trying to manage multiple tasks simultaneously.

Why it matters: Users are less likely to feel overwhelmed or make mistakes when each step focuses on one action. Clear, actionable steps enhance task completion success.

Correct

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

Incorrect

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

Include expected results within the same step

Users should know what to expect after completing each action. Including the expected result right after the step provides immediate feedback that they're on the right track.

Why it matters: Users are reassured when they see the expected outcome, which improves their confidence in the process and reduces frustration.

Correct

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

Incorrect

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

Use simple, accessible language

Write in simple, accessible language. Avoid jargon or overly technical terms unless absolutely necessary, and if used, provide explanations.

Why it matters: Simple language ensures a broader audience can understand your content, including those who might not have an advanced technical background. Clarity enhances usability and inclusivity.

Correct

  1. Use the slider to adjust the volume.
  1. Click Connect to start the connection.

Incorrect

  1. Manipulate the audio output level with the slider control interface.
  1. Initiate the process of establishing a connection by clicking 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 or rationale helps users understand the importance or purpose of a step, which can be crucial for steps that require decision-making.  If you have a lot to add, remember to keep it under 150 words or consider a separate section for the details. 

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

Correct

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

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

Incorrect

  1. Update the software and then restart your system.

Incorporate helpful visuals

Use visuals like screenshots or diagrams to enhance understanding, especially for software navigation or complex procedures. However, avoid overloading your document with unnecessary images.

Why it matters: Visual aids can reduce cognitive load, particularly for users navigating complex steps. However, balance is key—too many visuals can clutter the documentation.

Correct

  1. In the Settings window, select the Advanced tab.

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

Incorrect

  1. 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 for more options.