Kort oppsummert
- En brukerveiledning hjelper en bestemt person med å gjøre én bestemt oppgave.
- Hvert steg har én handling og sier hva brukeren skal se etterpå.
- Veiledningen er ikke ferdig før noen som ikke kjenner systemet, har fulgt den.
Hvem skal bruke den?
Spør alltid først: Hvem skal bruke veiledningen, og hva skal de ha fått til når de er ferdige?
En ny IT-medarbeider som kan terminalen, trenger en annen veiledning enn en lærer som aldri har åpnet en. Det samme systemet kan derfor trenge flere veiledninger. Finn ut hva mottakeren kan fra før, hva hen har tilgang til, og hvilke ord hen ikke kjenner.
Hva slags dokument er det?
En brukerveiledning er en handlingsveiledning: den hjelper brukeren med å gjennomføre én oppgave. Den er ikke en lærebok, et oppslagsverk eller en forklaring av hvorfor systemet virker som det gjør.
| Dokumenttype | Leseren spør | Eksempel |
|---|---|---|
| Handlingsveiledning | Hvordan gjør jeg dette? | Slik publiserer du en ny versjon av appen |
| Opplæring | Hvordan lærer jeg dette? | Din første container, steg for steg |
| Referanse | Hva er verdien eller kommandoen? | Liste over porter og tjenester |
| Forklaring | Hvorfor virker det slik? | Hvorfor vi bruker en reverse proxy |
Trenger brukeren en forklaring underveis, holder du den kort og legger den der brukeren trenger den.
Delene i veiledningen
| Del | Hva den svarer på |
|---|---|
| Mål | Hva har brukeren oppnådd når veiledningen er fulgt? |
| Før du begynner | Hvilke tilganger, programmer, filer og forkunnskaper trengs? |
| Steg-for-steg | Hva gjør brukeren, i hvilken rekkefølge, og hva skal hen se etter hvert steg? |
| Eksempler | Hvordan ser en kommando, en innstilling eller et riktig resultat ut? |
| Feilsøking | Hva gjør brukeren når resultatet ikke er som forventet? |
| Hvis du må angre | Hvordan tilbakestilles en endring som gikk galt? |
| Sjekkliste | Hvordan kontrollerer brukeren at alt er riktig til slutt? |
| Viktige tips | Hva har du lært som brukeren bør vite? |
| Kilder og kontroll | Hvilke kilder, hvilken versjon og hvilket testmiljø bygger veiledningen på? |
Slik skriver du et steg
Reglene bygger på standarder for bruksanvisninger og brukerdokumentasjon (IEC/IEEE 82079-1 og ISO/IEC/IEEE 26514).
- Start hvert steg med et verb i bydeform: «Åpne», «Kjør», «Kontroller».
- Ha én handling per steg og én instruksjon per setning. Hold setningene under omtrent 20 ord.
- Skriv hva brukeren skal se når steget er ferdig.
- Sett advarsler foran steget de gjelder, ikke etter.
- Bruk samme ord for det samme hele veien. Heter det «terminalen» ett sted, skal det ikke hete «konsollen» et annet.
- Forklar et fagord første gang det brukes.
Svakt steg:
Sett opp nettsiden og sjekk at alt virker.
Bedre steg:
3. Kontroller konfigurasjonen
Kjør:
sudo nginx -tDu skal se:
nginx: configuration file /etc/nginx/nginx.conf test is successfulSer du noe annet, gå til «Feilsøking».
Kommando, forventet resultat og plassholdere
- Sett kommandoer i en kodeblokk og forventet resultat i en egen blokk under.
- Bruk kodeformat for filnavn, filstier og kommandoer i løpende tekst, for eksempel
/etc/nginx/. - Skriv aldri ekte passord, nøkler eller interne adresser. Bruk tydelige plassholdere:
<server-ip>,<brukernavn>,<domene>. - Hold kodelinjer under omtrent 70 tegn, så de ikke kuttes på papir.
Feilsøking
Bygg feilsøkingen rundt det brukeren ser:
Symptom → mulige årsaker → undersøkelse → løsning → verifisering
| Symptom | Mulig årsak | Undersøk | Løsning | Slik ser du at det er løst |
|---|---|---|---|---|
| Nettsiden viser «502 Bad Gateway» | Tjenesten bak svarer ikke | Kjør docker compose ps og se om containeren kjører | Start containeren med docker compose up -d | Siden lastes, og docker compose ps viser «Up» i kolonnen STATUS |
Metoden bak står i Feilsøkingsmetode.
Skjermbilder
Bruk et skjermbilde bare når det hjelper brukeren å kjenne igjen et riktig resultat. Beskjær bildet, marker det viktigste med en pil eller et tall, og fjern sensitiv informasjon. Skriv en alternativ tekst som sier hva bildet viser.
- Windows: Windows-tast + Shift + S
- Mac: Cmd + Shift + 4
Skriv ut til PDF
- Åpne veiledningen i forhåndsvisning i VS Code, eller åpne filen på GitHub.
- Velg utskrift. Windows: Ctrl + P. Mac: Cmd + P.
- Velg «Lagre som PDF».
- Bla gjennom PDF-en. Kontroller at ingen kodelinjer, tabeller eller bilder kuttes.
Få respons før du leverer
La en medelev lese veiledningen før du sier at den er ferdig. Den som gir respons, svarer kort og viser til stedet i teksten:
- Korrekthet: Er det steg eller påstander du tviler på?
- Mottaker og struktur: Er det tydelig hvem veiledningen er for, og hva som må være på plass først?
- Språk og handling: Har hvert steg én handling og et forventet resultat? Er fagordene forklart?
- Sikkerhet: Står det noe som ikke burde vært publisert?
Gi to styrker og to konkrete forbedringer. Vær vennlig og konkret: «Jeg foreslår at du forklarer proxy i steg 2, fordi …» hjelper mer enn «uklart». Mer om å gi respons: NDLA Hvordan gi tilbakemeldinger?.
Oppgave 1 - Gjør svake steg bedre
Skriv om hvert steg slik at det har ett verb i bydeform, én handling og et forventet resultat. Del opp steg som inneholder flere handlinger.
- «Nå må containeren startes og det bør sjekkes at den kjører.»
- «Endre konfigurasjonen, og husk å teste den etterpå og så laste den inn på nytt.»
- «Logg inn på serveren med passordet Sommer2026! og gå til mappen med nettsiden.»
Oppgave 2 - Skriv en kort veiledning
Velg en oppgave du kan gjøre uten hjelp, for eksempel å starte en container eller publisere en endring på en nettside.
- Skriv hvem veiledningen er for, og hva de skal kunne gjøre etterpå.
- Skriv tre til seks steg med forventet resultat.
- Legg til minst én rad i feilsøkingen.
- La en medelev følge veiledningen uten at du forklarer noe. Rett det hen stoppet på.
Mer å lese
- NDLA: Lag bruksansvisninger og informasjon til ulike brukergrupper
- NDLA: Utvikle opplæringsmateriell
- Språkrådet: Klarspråk
- Diátaxis om de fire dokumenttypene (engelsk)