Sådan skriver du teknisk dokumentation

Vælg én opgave, én læser og én sandhedskilde. Skriv så trinene i klart sprog, test dem med en person, der ikke har skrevet dem, og skær alt væk, som ikke hjælper læseren med at blive færdig.

Før du skriver

God teknisk dokumentation begynder før den første sætning. Vælg først én opgave. Skriv for eksempel om at »forbinde en ny betalingsgateway«, ikke »dokumentere appen«. Det giver dig en klar målstreg og holder siden nyttig.

Dernæst skal du fastlægge læseren. En udvikler har brug for opsætningsnoter, kommandoer og edge cases. En supportmedarbejder har brug for symptomer, tjek og løsninger. En projektleder har måske brug for status, afhængigheder og overleveringsnoter. Én side kan gøre én af de ting godt, eller fejle på alle tre.

Samle derefter kilden til sandhed. Det kan være kode, tickets, skærmbilleder, designnoter, logs, en runbook eller en gammel manual, som stadig har ét godt afsnit. Hvis to kilder er uenige, så stop og spørg, hvilken der gælder, før du skriver et udkast.

Vælg formatet, før du begynder at skrive. En opsætningsguide, en referenceside og en fejlsøgningsside skal alle have forskellig form. For en controller til et hæve-sænke-bord kan en opsætningsguide forklare parring og kalibrering. En referenceside kan liste knappenavne og lysenes betydning. En fejlsøgningsside kan dække en fastlåst løftemekanisme eller et blinkende fejl-lys.

Sådan skriver du teknisk dokumentation

• Skriv resultatet først. Sig, hvad læseren kan gøre, når siden virker. Eksempel: »Når du er færdig, har du staging-appen forbundet til Stripe.«
• Brug et enkelt flow: formål, hvad du skal bruge, trin, resultat, løsninger. Det holder læseren i gang.
• Skriv én handling pr. trin. »Åbn admin-konsollen. Vælg Billing. Vælg Add payment method.« Det er lettere at følge end et langt afsnit med fem udsagnsord.
• Brug præcise navne på knapper, felter, mapper, kommandoer, fejlkoder og filnavne. Hvis skærmen siger Add payment method, så omdøb det ikke til New card i dokumentet.
• Hold ordene ens. Hvis du siger workspace i trin 1, så skift ikke til project area i trin 4.
• Sæt det sandsynlige problem ved siden af det trin, der skaber det. Hvis adgang ofte er problemet, så sig det der. Eksempel: »Hvis knappen mangler, så tjek, at du har Billing Admin-adgang.«
• Brug eksempler, der kan kopieres, til software og kode. Vis kommandoen, og vis så det forventede resultat lige efter. Det hjælper læseren med hurtigt at tjekke sin egen skærm.
• Skriv korte afsnit. Én idé pr. afsnit er nok. Hvis et afsnit har for mange idéer, så del det i to.
• Fjern alt, der ikke hjælper nogen med at blive færdig med opgaven. Baggrund er kun nyttig, hvis den forhindrer en fejl.
• Tilføj næste trin til sidst. Link for eksempel til testsiden, fejlsøgningssiden eller den opsætningsdel, der kommer bagefter.

En enkel skabelon til trin

Et fast trin-format gør dokumentationen let at læse, når opgaven bliver besværlig. Brug denne form til hvert trin: handling, resultat, løsning hvis nødvendigt. Det virker til softwareopsætning, projekt-overleveringer og kommandobaserede workflows.

Eksempel til en udviklerside: »Kør npm install. Du bør se, at pakkelisten opdateres. Hvis det fejler, så tjek, at Node 20 er installeret.« Det giver læseren noget at gøre, noget at forvente og noget at tjekke.

Før: »Derefter håndterer du afhængighedsproblemet.« Efter: »Kør npm install. Hvis du ser en tilladelsesfejl, så åbn terminalen igen som en bruger med skriveadgang.« Den anden version tager længere tid at skrive og er hurtigere at bruge.

Til en side om en controller til et hævesænkebord kan du skrive: »Hold op- og ned-knapperne nede i tre sekunder. Skærmen bør blinke én gang. Hvis den ikke gør det, så træk controlleren ud af stikket og prøv igen.« Det er klart, testbart og præcist.

Hvad god teknisk dokumentation indeholder

En nyttig side følger normalt denne rækkefølge: titel, kort introduktion, forudsætninger, trin, forventede resultater, løsninger, næste trin. Den rækkefølge virker, fordi den svarer på læserens spørgsmål i samme rækkefølge, som de dukker op.

Titlen skal nævne opgaven. Introduktionen skal fortælle læseren, hvem siden er til, og hvad den dækker. Forudsætningerne skal kun liste det, der blokerer fremdrift, som en konto, et kabel, en version eller et login.

Trinene skal stå i den rigtige rækkefølge, ikke den rækkefølge, der lyder smart. Sæt advarsler kun der, hvor de betyder noget. Tilføj et kort afsnit med løsninger til de mest almindelige fejl. Slut med et tydeligt stop, som en testkørsel eller en overlevering.

For en opsætningsside til en betalingsgateway kan det se sådan ud: »Forbind Stripe til staging-appen. Du skal have admin-adgang og en testnøgle. Følg trinnene for at indsætte nøglen, gemme indstillingen og køre en testbetaling. Hvis testen fejler, så tjek nøglen og kontotilladelserne. Gå derefter videre til siden om webhook-opsætning.«

Test den, før du udgiver

Stol ikke på udkastet, bare fordi det læses godt for dig. Giv det til en person, der ikke har skrevet det. Bed dem følge det uden hjælp. Se, hvor de holder pause, gætter eller går tilbage.

Hvis de holder pause, mangler siden måske en forudsætning eller et lille opsætningstrin. Tilføj det trin tæt på det første sted, hvor de har brug for det.

Hvis de gætter, er formuleringen uklar. Erstat 'indtast den rigtige værdi' med det præcise feltnavn, den præcise etiket eller den præcise filsti.

Hvis de går tilbage, er rækkefølgen forkert. Flyt trinnet tidligere, eller del siden op, så læseren ikke behøver at hoppe rundt.

Prøv at løse det forvirrende sted, ikke kun sætningen omkring det. Nogle gange er den rigtige løsning en ny forudsætning, et andet skærmbillede eller en ekstra side.

Til et hurtigt tjek kan du gennemgå tools manual check. Hvis du har brug for den samme vane til fysiske instruktioner, så sammenlign strukturen med this guide.

Hvad går der oftest galt

Det mest almindelige problem er for meget kontekst og for lidt handling. Læsere har ikke brug for en historielektion før knappenavnet.

En anden fejl er at blande opgaver på én side. Opsætning, fejlsøgning og reference kæmper alle om pladsen. Del dem op, når læseren skal skifte spor.

Skærmbilleder bliver hurtigt forældede. Brug dem kun til skærme, der ændrer sig sjældent. Når labels flytter sig meget, er en kort callout eller et beskåret billede bedre end et fuldt skærmbillede.

Vage ord skaber også problemer. Drop 'simply', 'easily' og 'just'. De løser ikke en fastlåst deployment eller en manglende tilladelse.

Når en side virker oppustet, så skær først det overflødige væk. Behold de trin, der får læseren frem til et fungerende resultat.

Hvor lang tid det tager

En kort how-to-side kan tage 30 til 60 minutter, hvis kilden er ren, og opgaven er enkel.

En normal software-opsætningsguide tager som regel 2 til 4 timer, når du medregner klargøring, gennemgang af trinene og redigering.

Et større projekt med edge cases, skærmbilleder og runder med gennemgang kan tage det meste af en dag.

Den langsomste del er som regel at bevise, at trinene virker, ikke at skrive dem. Hvis processen er rodet, så skriv dokumentationen, mens du udfører opgaven. Det fanger hurtigt manglende klik, skjulte antagelser og klodset formulering.

Når en videoversion hjælper

En skrevet side er stadig det bedste sted til søgning, reference og præcis tekst, du kan kopiere. En video hjælper, når opgaven har mange trin, skiftende skærme eller gentagne supportspørgsmål. Det er almindeligt ved onboarding, opsætning og praktiske procedurer.

Hvis du allerede har en samlevejledning eller en instruktion, kan en kort filmet version ligge ved siden af. Manual to Video gør en eksisterende manual til en animeret, tekstet trin-for-trin-film i dine brandfarver og dit logo. Den kan også fungere med en QR-kode på manualen, kassen, en produktside eller en supportartikel.