Artiklar

Fem tips för att skriva tydlig teknisk dokumentation

Att skapa tydlig och användbar dokumentation är lättare sagt än gjort. Det är viktigt att språket är begripligt, att nödvändig information är med och att texten är anpassad för målgruppen. I den här artikeln ger vi fem tips för hur du kan göra den tekniska dokumentationen tydligare.

Skriv för användaren

Vilken information som ska finnas med i dokumentationen beror delvis på målgruppen. Innan du börjar skriva och samla information bör du ta reda på;

  • Vilken är målgruppen? Vilken roll har de och hur väl kan de området dokumentationen handlar om.
  • Vad ska användarna använda dokumentationen till? Vad är syftet med den?
  • Vilket språk talar målgruppen?

När du kan besvara dessa frågor kan du också anpassa dokumentationen till användarna. Dokumentationen ska beskriva de termer som målgruppen inte förstår, den ska vara tydlig men inte heller innehålla mer information än nödvändigt. Det målgruppen redan vet behöver inte stå med. 

Val av termer

När du skriver eller går igenom dokumentation, var uppmärksam på termer som målgruppen eventuellt inte är bekanta med. För alla dessa termer bör det finnas en hänvisning till en förklaring.

För att en text ska vara tydlig är det också viktigt att använda sig av samma termer i hela dokumentationen. Om du använder olika termer av samma betydelse, kan texten bli otydlig och det kan bli svårt för användaren att förstå sambandet. 

Skriv i aktiv form, inte passiv form
Det finns flera fördelar med att skriva i aktiv form istället för passiv form. Framförallt så blir aktiv form i de flesta fall kortare och lättare att förstå. Dessutom omvandlar många läsare passiv form till aktiv form mentalt vilket gör att passiv form tar längre tid att bearbeta.

Exempel
Passiv form: Dörren öppnades för mig av en kvinna.
Aktiv form: En kvinna öppnade dörren för mig.

Korta ner meningar
Att hitta det kortaste sättet att formulera sig på kan ta lite tid men det kan ge goda resultat. Genom att korta ner dokumentationen, genom att formulera meningar på ett så kort och träffsäkert sätt som möjligt blir dokumentationen enklare att läsa, det går fortare och dessutom är den enklare att underhålla.

Två tips för att korta ner meningarna;
– Gå igenom din text och leta efter utfyllnadsord. Många gånger smyger sig onödiga ord in som inte nödvändigtvis är fel men som kan uteslutas utan att innebörden av meningen blir annorlunda. Exempel på ord som många gånger bara är utfyllnad är verkligen, absolut och kanske.

– Dela upp långa meningar. Försök att hålla dig till ett fokus per mening. Långa meningar går ofta att delas upp till fler kortare meningar vilket gör det enklare att ta till sig.

Dokumentets inledning
Bra dokumentation inleds med att beskriva dess omfattning. 

Exempel:
Det här dokumentet beskriver Dokumenteras rekryteringsprocess.

För att göra det ännu tydligare kan man dessutom beskriva vad dokumentet inte innehåller:

Exempel:
Det här dokumentet beskriver inte onboardingsprocessen för nyanställda.

Det är också en god idé att på samma sätt definiera målgruppen. 

Exempel:
Det här dokumentet riktar sig till rekryterande chefer på Dokumentera.

Genom att tydliggöra detta redan i dokumentets inledning kan man spara många läsares tid eftersom det gör det enklare att veta vilket dokument man ska läsa för att hitta den information man letar efter.

Behöver du hjälp med dokumentationen?

Dokumentera är ett ambitiöst och växande konsultbolag specialiserat på att skriva, analysera och organisera information och teknisk dokumentation. Sedan Dokumentera startade sin verksamhet 2007 har vi hjälpt ett stort antal nöjda företag och organisationer i olika branscher med kvalitativ dokumentation för både internt och externt bruk. Kontakta oss gärna så berättar vi mer om vad vi kan göra för dig.

 

DELA