Agil dokumentation tips #2: scope och detaljnivå

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.

Dela på facebook
Dela på twitter
Dela på linkedin
Dela på email

Jag hjälper dig med metoder, kunskap och erfarenheter kring produktdokumentation så att den blir både effektiv och användbar.

Fler inlägg

Skriva teknisk dokumentation i Word

Är inte Word gammalmodigt?

Är inte Word helt ute som manualformat? Det finns många avancerade verktyg för teknisk dokumentation. De flesta är xml-baserade som underlättar för single-sourcing, översättning och kanske continuous delivery. Just nu

Hacks för Rubiks kub

Vad vore livet utan hacks?

Jag älskar hacks av olika slag – knep och trick som förvandlar något svårt till något enkelt. Det kan handla om allt från att gnida paraffin på tröga byrålådor, till

Blixttal på Agila Sverige

Agil dokumentation – en oxymoron?

Är ”agil dokumentation” är en motsägelse i sig själv? Den frågan ställde jag mig i ett blixttal som jag höll på konferensen Agila Sverige i maj 2019. (Skrolla ner om

Gunilla Svanfeldt Omslag

Samtycke till marknadsföring

Vi lagrar informationen som du anger i formuläret för att kunna kontakta dig med nyhetsbrev, om uppdateringar och med erbjudanden. 

Markera kryssrutan i formuläret för att ge ditt samtycke till att vi skickar e-post till dig.

We use MailerLite as our marketing automation platform. By clicking below to submit this form, you acknowledge that the information you provide will be transferred to MailerLite for processing in accordance with their Privacy Policy and Terms of Service.