Hopp til innhold

Write yer user's guide,

Relevante sider
Andre relevante sider
Skip to content

Ahoy matey, this here’s a machine-translated scroll that may harbor some misfires!

Write a User’s Guide, Ye Scallywag

Short summary matey
  • A user guide helps a specific scamp perform one particular task.
  • Each step has one action an’ tells ye what to look for after that be done.
  • The guidance ain’t finished until some landlubber who don’t know the system’s ways have followed it through.

Who Should Be Usin’ It?

Always ask ye first: Who’s goin’ to use this guide, an’ what’ll they have achieved when their done?

A fresh deckhand o’ the IT crew who knows the command line needs a different set o’ instructions than a schoolteacher who ain’t never opened one. So the same ship may need several guides. Find out what yer audience already knows, what access they’ve got, an’ which words they don’t know yet.

What sort o’ document ‘tis it?

A user’s guide be a course of action: she helps ye land lubber get one job done. She ain’t no textbook, nor a reference book, nor an explanation o’ why the ship sails as she does.

Type o’ Document The Reader Asks Example
Course of Action How do I do this? Here be how to publish a new version o’ the app
Training How d’ye learn this? Yer first container, step by step
Reference What be the value or command? List o’ ports and services
Explanation Why does it work like that? Why we use a reverse proxy

If the crew needs an explanation along the way, keep her short an’ place her where they need her most.

The Pieces o’ the Guide

Part What it answers, matey
Goals Whatcha achieved when ye follow this guide to its end?
Before Ye Set Sail Which access rights, programs, files, an’ know-how be needful fer ye?
Step-by-Step What does the sailor do, in what order, an’ whatcha look for after each step?
Examples How does a command, setting, or right outcome appear afore yer eyes?
Troubleshootin’ What does the sailor do when the result ain’t as expected?
If Ye Must Undo It How d’ye reverse a change that went awry?
Checklist How does the sailor check that all’s right in the end?
Important Tips What have ye learned that the sailor should know?
Sources an’ Verification Which sources, which version, an’ which test environment does this guide rest upon?

How to write a step

These rules are built upon standards for user instructions and documentation (IEC/IEEE 82079-1 an’ ISO/IEC/IEEE 26514).

  • Kick off each step with a verb in the imperative form: “Open”, “Run”, “Check”.
  • Keep it to one action per step an’ one instruction per sentence. Keep yer sentences under about 20 words.
  • Write down what the mate should spy when the step be done.
  • Put warnings before the step they apply t’, not after.
  • Use the same word fer the same thing all along the way. If ye call it “the terminal” once, don’t go callin’ it “the console” another time.
  • Explain a technical term the first time ye use it.

Weak step:

Set up th’ website an’ check that evrythin be workin’.
Better step:

3. Check yer config, ye scallywag

Run this here command:

sudo nginx -t

Ye should be seein’ dis:

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

If ye spy sumthin else, head on over to “Troublin’s“.

Orders, Expected Result an’ Placeholders

  • Set yer orders inside a code block an’ put the expected result in its own separate block below it.
  • Use code format fer filenames, file paths, an’ commands when they’re scattered through ye regular text, like say /etc/nginx/.
  • Never write down real passwords, keys, or internal addresses. Ye best use clear placeholders: <server-ip>, <username>, <domain>.
  • Keep yer code lines shorter than about 70 characters so they don’t get cut off on paper.

Troublin’

Build yer troublin’ ‘round what the user’s seein’:

Sickness → likely causes → inspection → cure → verification
Sign o’ trouble What be likely to blame it on? How ye shall search for clues How to fix this mess How ye’ll know yer right an’ proper sorted out
The web page shows “502 Bad Gateway” The service behind the curtain ain’t answerin’ no calls Run docker compose ps and spy if the box is alive an’ kickin’ Breathe life into the beast with docker compose up -d The page loads smooth as silk, an’ docker compose ps shows “Up” in the STATUS column like a true flag flyin’ high

The method behind such deeds lies within [[Feilsokingsmetode Level 1 - Systematisk feilsøking|The Art of Seekin’ Trouble Level 1 - Systematic Huntin’]].

Screenshots

Use a screenshot only when it helps ye spot a proper result. Crop the image, mark the most important bit with an arrow or number, an’ scrub any sensitive info. Write some alt text that tells what the picture 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 printout. Windows: Ctrl + P. Mac: Cmd + P.
  3. Choose “Save as PDF”.
  4. Browse through the PDF. Check that no lines of code, tables, or pictures are cut off.

Get feedback afore ye deliver

Have a shipmate read the guide before ye declare it be done. The one givin’ feedback answers short an’ points tae where in the text:

  1. Accuracy: Be there any steps or claims ye doubt?
  2. Audience an’ structure: Is it clear who this guide is fer, an’ what must be ready first?
  3. Language an’ action: Does each step have just one action an’ expected result? Are the technical terms explained?
  4. Security: Is there anything that should not be published?

Give two strengths an’ two concrete improvements. Be kind an’ specific: “I suggest ye explain proxy in step 2, because…” helps more than “unclear”. More on how to give feedback: NDLA How to give feedback?.

Task 1 - Make weak steps better

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

  1. “Now ye must start da container an’ check dat she’s runnin’.”
  2. “Change de configuration, remember to test her after, an’ den load he back in again.”
  3. “Login t’ de server wi’ de password Sommer2026! an’ sail over t’ de folder wid’ de website.”

Task 2 - Yeer a short guide

Pick a job ye can do without no help, like startin’ a container or publishin’ a change on a webpage.

  1. Write down who this guide is fer, an what they’ll be able to do afterhand.
  2. Write three to six steps with the expected result.
  3. Add at least one line o’ troubleshootin’.
  4. Let a shipmate follow the guide without ye explainin’ nuffin. Fix it where they get stuck.

More to read