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.

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

Fler inlägg

Elbil

Läsa, förstå och komma ihåg?

Jag fattar inte varför vår elbil inte har växlar, jag erkänner. Förut tänkte jag att den var automatväxlad, men vet numera att så inte är fallet. Den har helt enkelt

Buffe med mat

Därför ska du skriva manualen som en buffé

Jag är en förespråkare av modulär teknisk dokumentation. Varför? För att det gör dokumentationen lättare att använda, lättare att skriva och framför allt lättare att uppdatera. Hur då? Modulärt julbord

Instruktioner för att laga soppa

User stories ger dig rätt instruktioner (del 2)

User stories visar vad er produkt faktiskt ska uträtta åt användaren. Eller snarare vad användaren vill göra. Du kan nu enkelt förstå vilka instruktioner som du behöver skriva. Välkommen till

Läsare av teknisk dokumentation

Fixa dokumentationen med user stories (del 1)

User stories kan ge dig en flygande start när du ska skriva teknisk dokumentation, särskilt manualer av olika slag. Det gäller oavsett om det är grundläggande manualer till slutanvändare, integrationsinstruktioner

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

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.