Tycker du att det är svårt att avgränsa vad du ska ta med i dokumentationen, och vad du kan utelämna? Det finns några knep att ta till för att hamna rätt.
Bakgrund
Som jag skrev om i mitt förra blogginlägg, så hade jag tre tips för att skapa agil dokumentation när jag höll mitt blixttal på Agila Sverige 2019. Men på tio minuter skulle jag aldrig hinna berätta om alla tre. Så jag tog det första tipset i talet. Sedan föreslog jag att vi skulle prata mer om de andra två tipsen på Open space-sessionen på eftermiddagen.
För dig som inte var där, så kommer här tips nummer 2.
Tips #2 för agil dokumentation
Mitt andra tips för agil dokumentation handlar alltså om hur du hittar rätt scope och detaljnivå i din dokumentation. Tricket är att tydligt definiera målgrupp och syfte. Det här jag har skrivit om tidigare i inlägget Just in case or just for when.
Det handlar om att besluta dig genom vilken kameralins du ska titta på produkten. Om du inte vet vad du vill avbilda med din kamera och på vilket avstånd, så är det svårt att välja rätt lins för att rätt saker ska komma med på bild och avbildas med skärpa. Har du fel lins, ja då spelar det ingen roll hur bra kameran är, resultatet kommer troligen inte att bli särskilt bra.
På samma sätt, om du inte vet vem som ska läsa det du skriver, och i vilket situation, så är det omöjligt att skriva en effektiv och användarvänlig dokumentation.
Om du ska skriva produktinformation för en tvättmaskin så kommer den se rätt olika ut beroende på vem du riktar dig till. Familjens tonåring, till serviceteknikern eller till tillverkarens säljarkår?
Samma sak gäller om du ska skriva release notes för er nya version av – säg – tidrapporteringssystemet som ni utvecklar. Ok, du vet att du ska skriva om vad som har ändrats i systemet. Men för att veta vad av allt det nya du ska ta med, och hur du ska förklara det, så måste du veta vem som är läsaren av dina release notes. Är det slutanvändaren som läser? Kundens it-avdelning? Eller är det systemadministratörerna, eller rent av kundens inköpsavdelning?
Ibland är det också i själva verket interna release notes du skriver. Det vill säga, är de egentligen utvecklingsteamets sätt att informera resten av din organisation vad det är ni har jobbat med den senaste tiden?
Om det är så att alla dessa roller är tänkbara läsare, ja då bör du nog rikta olika delar av dina release notes till de olika målgrupperna.
Slutanvändaren vill veta:
- hur hen ska göra för att fylla i tidrapporten
- varför ni har kastat om kolumnerna
- vart knappen för att byta attesterare har tagit vägen
- hur hen hittar de nya fiffiga snabbkommandona som ni har skapat för att göra livet lättare för användaren.
Administratören vill veta:
- hur det nya sättet att tidrapportera avspeglas i månadsrapportens sammanställning
- var hen ställer in behörigheter för attesterare.
It-avdelningen vill veta:
- de nya systemkraven
- hur uppgraderingen bör gå till för att databasen inte ska krascha.
Så ta en målgrupp i taget. Välj kameralins och ställ in skärpan. Vad behöver den här målgruppen veta om din produkt? Då blir din dokumentation användarcentrerad.
Om du börjar i andra änden och frågar dig vad som har ändrats i produkten, då kommer dokumentationen att bli produktcentrerad. Och det är faktiskt inte produkten som är målgruppen och som ska läsa dokumentationen. Med fel lins blir bilden suddig.
