Slik skriver du teknisk dokumentasjon

Lær hvordan du skriver teknisk dokumentasjon steg for steg, fra omfang og struktur til testing, gjennomgang og vedlikehold for programvare eller prosjekter.

Velg én oppgave, én leser og én sannhetskilde. Skriv så stegene i enkelt språk, test dem med noen som ikke skrev dem, og fjern alt som ikke hjelper leseren med å bli ferdig.

Før du skriver

God teknisk dokumentasjon starter før første setning. Velg én oppgave først. Skriv for eksempel om «koble til en ny betalingsløsning», ikke «dokumenter appen». Da får du en tydelig sluttlinje og en side som faktisk er nyttig.

Deretter må du definere hvem leseren er. En utvikler trenger oppsettnotater, kommandoer og kanttilfeller. En supportmedarbeider trenger symptomer, kontroller og løsninger. En prosjektleder kan trenge status, avhengigheter og overleveringsnotater. Én side kan fungere godt for én av dem, eller bomme på alle tre.

Samle så sannhetskilden. Det kan være kode, saker, skjermbilder, designnotater, logger, en runbook eller en gammel håndbok som fortsatt har ett godt avsnitt. Hvis to kilder er uenige, stopp og spør hvilken som gjelder før du skriver utkastet.

Velg formatet før du begynner å skrive. En oppsettsguide, en referanseside og en feilsøkingsside trenger hver sin form. For en kontroller til hev- og senk-pult kan en oppsettsguide forklare sammenkobling og kalibrering. En referanseside kan liste knappenavn og lysbetydninger. En feilsøkingsside kan ta for seg en fastlåst løftemekanisme eller et blinkende feillys.

Slik skriver du teknisk dokumentasjon

Skriv resultatet først. Si hva leseren kan gjøre når siden er ferdig. Eksempel: «Ved slutten vil du ha koblet staging-appen til Stripe.»
Bruk en enkel flyt: formål, det du trenger, steg, resultat, løsninger. Da holder du leseren på sporet.
Skriv én handling per steg. «Åpne administrasjonskonsollen. Velg Fakturering. Velg Legg til betalingsmåte.» Det er lettere å følge enn et langt avsnitt med fem verb.
Bruk nøyaktige navn på knapper, felt, mapper, kommandoer, feilkoder og filnavn. Hvis skjermen sier Legg til betalingsmåte, ikke kall det Nytt kort i dokumentet.
Hold på begrepene. Hvis du sier arbeidsområde i steg 1, ikke bytt til prosjektområde i steg 4.
Plasser det sannsynlige problemet ved siden av steget som skaper det. Hvis tilgang ofte er problemet, si det der. Eksempel: «Hvis knappen mangler, sjekk at du har Billing Admin-tilgang.»
Bruk kopierbare eksempler for programvare og kode. Vis kommandoen, og vis deretter forventet resultat rett etterpå. Det hjelper leseren med å sjekke skjermen sin raskt.
Skriv korte avsnitt. Én idé per avsnitt er nok. Hvis et avsnitt har for mange ideer, del det i to.
Fjern alt som ikke hjelper noen med å fullføre oppgaven. Bakgrunn er bare nyttig hvis den hindrer en feil.
Legg til neste steg til slutt. Lenke for eksempel til testsiden, feilsøkingssiden eller den delen av oppsettet som kommer etterpå.

En enkel stegmall

Et stabilt stegformat gjør dokumentasjonen lett å lese når oppgaven blir krevende. Bruk denne formen for hvert steg: handling, resultat, løsning ved behov. Det fungerer for programvareoppsett, prosjektleveranser og arbeidsflyter basert på kommandoer.

Eksempel for en utviklerside: «Kjør npm install. Du skal se at pakkelisten oppdateres. Hvis det feiler, sjekk at Node 20 er installert.» Det gir leseren noe å gjøre, noe å forvente og noe å sjekke.

Før: «Deretter håndterer du avhengighetsproblemet.» Etter: «Kjør npm install. Hvis du ser en tillatelsesfeil, åpne terminalen på nytt som en bruker med skrivetilgang.» Den andre versjonen er tregere å skrive og raskere å bruke.

For en side om en kontroller til pult kan du skrive: «Hold inne opp- og ned-knappene i tre sekunder. Displayet skal blinke én gang. Hvis det ikke gjør det, koble fra kontrolleren og prøv igjen.» Det er enkelt, testbart og konkret.

Hva god teknisk dokumentasjon inneholder

En nyttig side følger vanligvis denne rekkefølgen: tittel, kort åpning, forutsetninger, steg, forventede resultater, løsninger, neste steg. Den rekkefølgen fungerer fordi den svarer på leserens spørsmål i samme rekkefølge som de dukker opp.

Tittelen bør navngi oppgaven. Åpningen bør fortelle hvem siden er for og hva den dekker. Forutsetningene bør bare liste det som stopper fremdriften, for eksempel en konto, en kabel, en versjon eller en innlogging.

Stegene bør stå i den virkelige rekkefølgen, ikke den som høres smart ut. Legg inn advarsler bare der de trengs. Legg til en kort løsningseksjon for de vanligste feilene. Avslutt med et tydelig stoppunkt, som en testkjøring eller en overlevering.

For en oppsettside for en betalingsløsning kan det se slik ut: «Koble Stripe til staging-appen. Du trenger administrator-tilgang og en testnøkkel. Følg stegene for å lime inn nøkkelen, lagre innstillingen og kjøre en testbetaling. Hvis testen feiler, sjekk nøkkelen og kontotillatelsene. Gå deretter til siden for webhook-oppsett.»

Test det før du publiserer

Ikke stol på utkastet bare fordi det leses godt av deg. Gi det til noen som ikke skrev det. Be dem følge det uten hjelp. Se hvor de stopper opp, gjetter eller går tilbake.

Hvis de stopper opp, kan siden mangle en forutsetning eller et lite oppsettssteg. Legg til det steget nær det første stedet de trenger det.

Hvis de gjetter, er formuleringen uklar. Bytt ut «angi riktig verdi» med det nøyaktige feltnavnet, etiketten eller filstien.

Hvis de går tilbake, er rekkefølgen feil. Flytt steget tidligere, eller del opp siden slik at leseren ikke må hoppe rundt.

Prøv å fikse den forvirrende delen, ikke bare setningen rundt den. Noen ganger er den virkelige løsningen en ny forutsetning, et nytt skjermbilde eller en egen side.

For en rask sjekk kan du gå gjennom tools manual check. Hvis du trenger den samme vanen for fysiske instruksjoner, kan du sammenligne strukturen med this guide.

Hva går oftest galt

Det vanligste problemet er for mye kontekst og for lite handling. Leseren trenger ikke en historietime før knappenavnet.

En annen feil er å blande flere oppgaver på én side. Oppsett, feilsøking og referanse kjemper alle om plassen. Del dem opp når leseren må bytte tankesett.

Skjermbilder blir fort utdaterte. Bruk dem bare for skjermer som endrer seg sjelden. Når etiketter flytter seg mye, bruk en kort utheving eller et beskåret bilde i stedet for et skjermbilde av hele skjermen.

Vage ord skaper også trøbbel. Dropp «simpelthen», «lett» og «bare». De fikser ikke en fastlåst utrulling eller en manglende tillatelse.

Når en side virker for oppblåst, kutt først det som er ekstra. Behold trinnene som får leseren fram til et fungerende resultat.

Hvor lang tid det tar

En kort veiledningsside kan ta 30 til 60 minutter hvis kildematerialet er ryddig og oppgaven er enkel.

En vanlig oppsettsguide for programvare tar som regel 2 til 4 timer når du tar med utkast, kontroll av trinnene og redigering.

En større prosjektside med kanttilfeller, skjermbilder og runder med gjennomgang kan ta det meste av en dag.

Den trege delen er som regel å bevise at trinnene fungerer, ikke å skrive dem. Hvis prosessen er rotete, skriv dokumentasjonen mens du gjør oppgaven. Da fanger du opp manglende klikk, skjulte antakelser og klønete formuleringer raskt.

Når en videoversjon hjelper

En skrevet side er fortsatt det beste stedet for søk, referanse og nøyaktig tekst du kan kopiere. En video hjelper når oppgaven har mange trinn, skjermer som endrer seg, eller gjentatte supportspørsmål. Det er vanlig ved onboarding, oppsett og praktiske prosedyrer.

Hvis du allerede har en monteringsanvisning eller en bruksanvisning, kan en kort filmet versjon ligge ved siden av. Manual to Video gjør en eksisterende monteringsanvisning om til en animert, tekstet steg-for-steg-film i bedriftens farger og med logoen din. Den kan også fungere med en QR-kode på manualen, esken, en produktside eller en supportartikkel.

Spørsmål

Hva er det beste formatet for teknisk dokumentasjon?

Det beste formatet er det som passer til oppgaven. Bruk en prosedyreside når leseren skal gjøre noe. Bruk en referanseside når de trenger nøyaktige verdier eller kommandoer. Bruk feilsøking når de allerede har et problem. For eksempel bør en oppsettside for en skriver vise oppsettstrinnene, en portliste bør være en referanseside, og hjelp ved papirstopp bør være feilsøking. Hvis du legger alt på én side, må leseren lete etter delen de trenger.

Hvordan skriver du dokumentasjon for utviklere?

Start med miljøet, den nøyaktige kommandoen og forventet resultat. Utviklere vil ofte ha oppsett, kodeeksempler, API-kall og feilspor. Hold eksempelkommandoer klare til å kopiere. Vis hvordan suksess ser ut rett etter kommandoen. Hvis et trinn er avhengig av en versjon, tillatelse eller config-fil, si det med en gang. En enkel struktur er: tittel, forutsetninger, installasjon, kjøring, test, feil, neste steg.

Hva bør en teknisk manual inneholde?

En nyttig teknisk manual har som regel oppgavenavn, en kort innledning, forutsetninger, trinnvise handlinger, forventet resultat og en kort feilseksjon. Legg til neste steg når leseren er ferdig. Hvis manualen er for programvare eller et prosjekt, ta med nøyaktige navn og eksempler som kan kopieres der de hjelper. For et første utkast, hold det stramt. For den endelige versjonen, legg bare til kontrollene, advarslene og eksemplene som hindrer reelle feil.

Hvordan holder du teknisk dokumentasjon oppdatert?

Se gjennom siden når produktet endrer seg, når support stadig får det samme spørsmålet, eller når et trinn ikke lenger stemmer med skjermen. En jevn kontroll, for eksempel månedlig for produkter som endrer seg raskt, er enklere enn en stor omskriving senere. Hvis en side er gammel, marker delene du stoler mindre på, og test dem først på nytt.

Hvordan gjør du programvaredokumentasjon lettere å følge?

Bruk én handling per trinn, nøyaktige etiketter og korte avsnitt. Plasser resultatet ved siden av handlingen, så leseren kan sjekke selv. Fjern bakgrunnsstoff som ikke hjelper dem å fullføre oppgaven. Test så utkastet med noen som ikke kjenner prosessen. Hvis de står fast, er løsningen som regel mer detaljer, ikke flere ord. Hvis skjermbilder hjelper, bruk dem for sjeldne eller vanskelige skjermer, ikke for hvert klikk.