På mitt första jobb som teknisk skribent arbetade jag med teknisk dokumentation som var skriven i vad vi kan kalla ”flödesform”. Jag fick känslan av att skribenten hade satt sig ner och berättat allt hen visste om en viss programdel och läsaren förväntades börja på första sidan och läsa på tills dokumentet var slut, vilket ibland var 40 sidor senare. Då skulle läsaren ha tagit del av allt viktigt och förstått de viktiga flödena.
Stora mängder ostrukturerad löptext
Eftersom det rörde sig om en omfattande produkt så fanns det i storleksordningen 80 sådana dokument, och då fanns ändå programdelar som ännu inte var dokumenterade.
Mitt jobb var att dels fylla på med de delar som fattades, dels att underhålla den befintliga dokumentationen. Men att hålla efter en sådan omfattande textmassa som inte är tydligt strukturerad är oerhört tidskrävande.
Jag kunde inte hantverket
Jag stod också och velade mellan att bara uppdatera i löptexten och försöka anamma samma berättande stil, eller försöka strukturera upp dokumentationen. Jag hade aldrig jobbat med teknikinformation tidigare och hade ingen metod för skrivandet, jag kunde inga verktyg och kände inte till några principer som Topic based authoring, Information mapping eller DITA.
Aldrig ikapp
Jag låg konstant efter, textmassan var oöverblickbar och vi hade inget strukturerat sätt för mig att få reda på vad som behövde uppdateras. Efter en tid blev jag ansvarig för att skriva release notes vilket gjorde att jag lyckades ta reda på vad som hade hänt i den senaste releasen, men det fanns ju inte en chans att jag efter det skulle hinna göra alla uppdateringarna i 1500 sidor text, varav en stor del av upprepningar eftersom de var skrivna som mer eller mindre självständiga dokument.
Resultatet blev en dokumentkoloss, som ingen läste, särskilt inte som innehållet blev mer och mer ouppdaterat. Dokumentationen skulle ha behövt ett rejält omtag, men det var svårt att motivera något som skulle kräva så stora resurser. Jag var också osäker på bästa sättet att gå tillväga.
Det finns bra metoder och arbetssätt!
Sedan dess har jag jobbat med många andra produkter och lärt mig både metoder och verktyg, som jag önskat att jag kunnat använda tidigare.
Om du känner igen dig i problemen som jag hade, eller åtminstone inte vill riskera att hamna där, så har jag följande tips för att hålla din dokumentation uppdaterad och under kontroll:
- Begränsa mängden levande dokumentation
- Definiera triggers till uppdatering i befintliga processer
- Överväg att låta fler uppdatera dokumentationen
- Strukturera dokumentationen
- Följ riktlinjer för dokumentationen
Tips 1: Begränsa mängden levande dokumentation
Var lite snåla med antalet dokument som ni förbinder er att hålla uppdaterade, men håll dessa under väldigt god uppsyn:
- Skriv ner vilka dokument som ska hållas uppdaterade, efter att ni har gjort en grundlig analys av nytta/kostnad eller av regulatoriska krav.
- Se till att dokumenten står med på checklistan som ni går igenom innan release av produkten (eller motsvarande händelse).
- Se till att andra dokument som ni producerar tydligt anger att de inte kommer att uppdateras framöver.
Tips 2: Definiera triggers till uppdatering
Uppdatering av dokumentationen behöver komma in som en del i till exempel utvecklingsprocessen och supportprocessen. Ni behöver identifiera triggers för uppdateringen, eller på något sätt knyta uppdateringen till vissa befintliga moment.
Uppdatering av olika delar av dokumentationen kommer troligtvis att triggas av olika saker.
Kanske kommer ni fram till att:
- troubleshooting-avsnitt uppdateras i samband med supportärenden
- uppdatering av referensinformation knyts till utvecklingsärenden i någon form
- versionsnyheter skrivs innan ny release släpps
- Getting started ögnas igenom antingen vid ny release, eller med visst tidsintervall.
Att uppdateringen triggas av olika moment eller händelser är inte nödvändigtvis samma sak som att det är den personen som utför momentet (till exempel utvecklaren i ett utvecklingsärende) som faktiskt gör själva uppdateringen i dokumentationen. Den personen kan i sin tur skicka uppdraget att uppdatera dokumentationen vidare till den som ska göra ändringen, tillsammans med lämplig input.
Olika individer har olika förutsättningar, intresse, kompetens och tidsutrymme för att uppdatera dokumentation och det är rimligt att utnyttja respektive individs kärnkompetens. (Det är här tekniska skribenter kommer in… )
Tips 3: Överväg att låta fler ändra i dokumentationen
Ni kan också fundera på vilka som ska ha rätt att redigera i dokumentationen. Ska alla hos er internt kunna skriva, redigera och ta bort innehåll? Ska även kunder och användare ha rätt att ändra? Föreslå ändringar?
Att göra dokumentationen till open source kan ju vara ett sätt att se till att den hålls à jour, men då behåller ni inte riktigt kontrollen över vad som står. Som ett slags mellansteg kan man tänka sig en slags staging-procedur, så att ändringar godkänns av någon insatt person innan de publiceras.
Om det finns regulatoriska krav på er produkt så skulle jag undvika att öppna upp för utomstående. Även interna ändringar behöver då följa en fastslagen process för publicering.
Tips 4: Strukturera dokumentationen
Ju mer strukturerad er dokumentation är, desto lättare är det för ALLA att uppdatera, i vilken dokumentation som helst. Det blir även lättare att tillfälligt ta in en extern person för hjälp med uppdateringen.
En tydlig struktur gör det också lättare för alla att veta vilken information som efterfrågas i dokumentationen. Inom kort kommer alla utvecklare att veta att de måste lägga till nya utvecklingsverktyg i listan i utvecklingsplanen, att nya databasversionen behöver anges i systemkraven och att ändringar i inloggningsproceduren betyder att användarmanualen behöver uppdateras.
Tips 5: Följ fastslagna riktlinjer
Med tydliga, nedskrivna riktlinjer för dokumentationen behöver inte alla uppfinna hjulet på nytt. Följ helt enkelt mallen för hur instruktioner ska se ut, vilket typsnitt du ska använda och hur du ska göra markeringar i bilder.
När allt är tydligt uppstyrt och alla känner till vad som gäller så kan alla göra uppdateringar! Då är det mycket större chans att uppdateringarna blir av och att dokumentationen kommer till användning.
Vill du ha hjälp med att reda ut hur ni ska göra med uppdateringar av dokumentationen, hör av dig till info@gunillasvanfeldt.se.
