Hopp til innhold

Write up a user guide

Relevante sider
Andre relevante sider
Skip to content

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

Pen a User Guide

Summed up short an’ quick
  • A user guide helps one specific partner handle one particular job.
  • Each step has one move an’ tells ya what to look for after that.
  • The guide ain’t done till someone who don’t know the system inside out has followed it through.

Who Should Use It?

Always ask first: Who is gonna use this guide, an’ what’s they supposed to have got done by the time they’re finished?

A fresh new IT hand who can handle a terminal needs different guidance than a teacher who ain’t ever opened one up before. So that same ol’ system might need more’n just one set of instructions. Figure out what your audience already knows, what access they’ve got on their hands, an’ which words they don’t know yet.

What Kind of Document Is It?

A user guide is a how-to manual: it helps the user complete one task. It ain’t no textbook, reference book, or explanation on why the system works the way it does.

Doc Type Reader Asks Example
How-To Manual How do I get this done? Here’s how ya publish a new version o’ the app
Training How do I learn this here thing? Yer first container, step by step
Reference Whatcha value or command be? List o’ ports an’ services
Explanation Why does it work like that? Why we use a reverse proxy

If the rider needs an explanation along the trail, keep it short an’ put it right where they need it.

Parts in the Guide

Part What it answers
Goals What has the user achieved when following the guide is done?
Before you start What access, programs, files, and prior knowledge are needed?
Step-by-step What does the user do, in what order, and what should they look for after each step?
Examples What does a command, setting, or correct result look like?
Troubleshooting What does the user do if the outcome isn’t as expected?
If you need to undo How is a change that went wrong rolled back?
Checklist How does the user verify everything is right in the end?
Key Tips What have we learned that the user needs to know?
Sources & Verification Which sources, version, and testing environment form the basis of this guide?

How to write a step

These rules are built on standards for user manuals and documentation (IEC/IEEE 82079-1 and ISO/IEC/IEEE 26514).

  • Kick off every step with a verb in the imperative form: “Open,” “Run,” “Check.”
  • Stick to one action per step and one instruction per sentence. Keep sentences under about 20 words.
  • Describe what the user should see once the step is done.
  • Place warnings before the step they apply to, not after.
  • Use the same word for the same thing all the way through. If it’s called “the terminal” in one spot, don’t call it “the console” somewhere else.
  • Define a technical term the first time you use it.

Weak step:

Set up the website an’ check that everything’s workin’.
Better step:

3. Check yer setup

Run this:

sudo nginx -t

You oughta see:

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

If you spot somethin’ else, head on over to “Troubleshootin’”.

Commands, Expected Results, and Placeholders

  • Put commands in a code block and expected results in a separate block below.
  • Use code formatting for filenames, file paths, and commands in running text, for example /etc/nginx/.
  • Never write real passwords, keys, or internal addresses. Use clear placeholders: <server-ip>, <username>, <domain>.
  • Keep code lines under about 70 characters so they don’t get cut off on paper.

Troubleshootin’

Build them troubleshoots ‘round what the user’s seein’:

Symptoms → possible causes → investigation → solution → verification
Symptom Possible cause Investigate Fix How ya know it’s fixed
The webpage shows a “502 Bad Gateway” That service in back ain’t answerin’ Run docker compose ps and see if that container is runnin’ Get that container started with docker compose up -d The page loads, an’ docker compose ps shows “Up” under the STATUS column

The method behind this is written down in [[Troubleshooting Method Level 1 - Systematic Troublinghootin’|Troubleshootin’ Method]].

Screenshots

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

  • Windows: Windows key + Shift + S
  • Mac: Cmd + Shift + 4
![Nginx Proxy Manager shows the proxy host with status Online](bilder/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. Review the PDF. Check that no lines of code, tables, or images are cut off.

Get Feedback Before You Deliver

Have a classmate read the guide before you call it done. The one giving feedback should keep it short and point to the specific spot in the text:

  1. Accuracy: Are there any steps or claims that don’t sit right with ya?
  2. Audience and Structure: Is it clear who this guide is for, and what needs be set up first?
  3. Language and Action: Does each step have just one action and an expected result? Are the technical terms explained proper-like?
  4. Safety: Is there anything written down that shouldn’t see the light of day?

Give two strengths and two concrete improvements. Be kind and specific: “I reckon you oughta explain proxy in step 2, ‘cause…” helps more than just sayin’ “unclear.” More on givin’ feedback: NDLA How do we give feedback?

Task 1 - Make Weak Steps Better

Rewrite each step so it has one imperative verb, one action, and an expected result. Break down steps that contain multiple actions.

  1. “Now the container needs to be started and you should check if it’s running.”
  2. “Change the configuration, remember to test it afterwards, and then reload it.”
  3. “Log into the server with the password Sommer2026! and go to the folder for the website.”

Task 2 - Write a Short Guide

Pick a job you can handle on your own, like startin’ up a container or publishin’ a change to a website.

  1. Write down who this guide is fer, an’ what they’ll be able to do after readin’ it.
  2. Lay out three to six steps with the expected outcome.
  3. Add at least one line o’ troubleshooting tips.
  4. Have a classmate follow the guide without y’all explainin’ nothin’. Fix whatever caused ‘em to get stuck.

More Readin’