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

Musfälla

Trick för att locka information ur utvecklare

Att få fram underlag till teknisk dokumentation är verkligen en utmaning. Själv har jag provat allt. Jag har mutat utvecklare med kakor. Intervjuat stressade projektledare. Filtrerat ofantliga mängder med utvecklingsärenden

Tips till dig som skriver lathund i affekt

Behöver dina kunder en lathund för er produkt? Eller behöver ni själva en intern lathund på kontoret för att komma tillrätta med reseräkningarna? Lathundar kan vara många olika saker. Allt

Är din dokumentation agil?

Ni har en agil utvecklingsprocess. Check. Ni har kanske till och med skickat ledningen på kurs och har nu en agil organisation i stort. Toppen! Men hur står det till

Vad kostar en manual

Vad kostar en manual?

Tid är pengar. Den största kostnaden för teknisk dokumentation är ofta tiden som skribenten lägger ner. Visst kan olika slags verktyg kosta pengar. Om du dessutom skickar manualen på tryck

Illustrerad instruktion

6 olika sätt att skriva instruktioner

Det finns många olika sätt att skriva instruktioner. Ett format är inte nödvändigtvis bättre än ett annat. Flera faktorer styr vilken typ av instruktion som fungerar bäst:  personliga preferenser: vissa

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.