Hopp til innhold

Write a user guide

Relevante sider
Andre relevante sider
Skip to content

This is a machine-translated text that may contain errors!

Brief summary
  • A user guide helps a specific person perform one specific task.
  • Each step has one action and states what the user should see next.
  • The guide is not finished until someone unfamiliar with the system has followed it.

Who should use it?

Always ask first: Who will use the guide, and what should they have accomplished when they are done?

A new IT employee who knows how to use a terminal needs a different guide than a teacher who has never opened one. The same system may therefore require multiple guides. Find out what the recipient already knows, what access they have, and which terms they are unfamiliar with.

What kind of document is it?

A user guide is an action guide: it helps the user complete a single task. It is not a textbook, a reference work, or an explanation of why the system works as it does.

Document type The reader asks Example
Action guide How do I do this? This is how you publish a new version of the app
Training How do I learn this? Your first container, step by step
Reference What is the value or command? List of ports and services
Explanation Why does it work like that? Why we use a reverse proxy

If the user needs an explanation along the way, keep it brief and place it where the user needs it.

Parts of the guide

Part What it answers
Goals What has the user achieved when following the guide is complete?
Before you begin Which access rights, programs, files, and prerequisites are needed?
Step-by-step What does the user do, in what order, and what should they expect to see after each step?
Examples How does a command, setting, or correct result look?
Troubleshooting What does the user do if the result is not as expected?
If you need to undo How is an incorrect change reverted?
Checklist How does the user verify that everything is correct at the end?
Important tips What have you learned that the user should know?
Sources and verification Which sources, which version, and which testing environment form the basis for the guide?

How to write a step

The rules are based on standards for instructions and user documentation (IEC/IEEE 82079-1 and ISO/IEC/IEEE 26514).

  • Start each step with a verb in the imperative mood: “Open”, “Run”, “Check”.
  • Have one action per step and one instruction per sentence. Keep sentences under approximately 20 words.
  • Write what the user should see when the step is complete.
  • Place warnings before the step they apply to, not after.
  • Use the same word for the same thing throughout. If it is called “the terminal” in one place, it should not be called “the console” elsewhere.
  • Explain a technical term the first time it is used.

Weak step:

Set up the website and check that everything works.
Better step:

3. Check the configuration

Run:

sudo nginx -t

You should see:

nginx: configuration file /etc/nginx/nginx.conf test is successful

If you see anything else, go to “Troubleshooting”.

Command, expected result, and placeholders

  • Place commands in a code block and the expected result in a separate block below it.
  • Use inline code formatting for filenames, file paths, and commands within running text, for example /etc/nginx/.
  • Never write actual passwords, keys, or internal addresses. Use clear placeholders: <server-ip>, <username>, <domain>.
  • Keep lines of code to approximately 70 characters so they are not cut off on paper.

Troubleshooting

Build troubleshooting around what the user sees:

Symptom → possible causes → investigation → solution → verification
Symptom Possible cause Investigate Solution How to verify it is resolved
The website displays “502 Bad Gateway” The backend service does not respond Run docker compose ps and check if the container is running Start the container with docker compose up -d The page loads, and docker compose ps shows “Up” in the STATUS column

The method behind this is described in [[Troubleshooting Method Level 1 - Systematic Troubleshooting|Troubleshooting Method]].

Screenshots

Use a screenshot only when it helps the user recognize a correct result. Crop the image, highlight the most important part with an arrow or number, and remove sensitive information. Write alternative text that describes what the image shows.

  • Windows: Windows key + Shift + S
  • Mac: Cmd + Shift + 4
![Nginx Proxy Manager shows the proxy host with status Online](images/proxy-online.png)
  1. Open the guide in preview in VS Code, or open the file on GitHub.
  2. Select print. Windows: Ctrl + P. Mac: Cmd + P.
  3. Choose “Save as PDF”.
  4. Scroll through the PDF. Ensure that no lines of code, tables, or images are cut off.

Get feedback before you deliver

Have a classmate read the guide before you say it is finished. The person giving feedback should respond briefly and point to specific parts of the text:

  1. Accuracy: Are there any steps or claims you are unsure about?
  2. Audience and structure: Is it clear who the guide is intended for, and what needs to be in place first?
  3. Language and action: Does each step have one action and an expected result? Are technical terms explained?
  4. Safety: Is there anything that should not have been published?

Provide two strengths and two concrete improvements. Be kind and specific: “I suggest that you explain proxy in step 2, because…” helps more than “unclear.” More on how to give feedback: NDLA How do I provide feedback?

Task 1 - Make weak steps better

Rewrite each step so that it has one imperative verb, a single action, and an expected result. Split up steps that contain multiple actions.

  1. “Now the container needs to be started and it should be checked that it is running.”
  2. “Change the configuration, remember to test it afterwards, and then reload it.”
  3. “Log in to the server with the password Sommer2026! and go to the folder for the website.”

Task 2 - Write a short guide

Choose a task that you can perform without help, for example starting a container or publishing a change to a website.

  1. Write who the guide is intended for, and what they should be able to do afterwards.
  2. Write three to six steps with the expected result.
  3. Add at least one line of troubleshooting.
  4. Have a classmate follow the guide without you explaining anything. Correct them where they get stuck.

More to read