Ä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 med dokumentationen? Vilka nya metoder har ni lärt er för att skriva och ta hand om er tekniska dokumentation?

Var hör dokumentationen hemma?

Dina funderingar kanske liknar de frågor som jag ofta får:

  • Ska manualen räknas som en del av ”definition of done”?
  • Ska manualen följa en egen process, parallellt med utvecklingsarbetet?
  • Finns det verktyg för manualer som passar för agila processer?

Mitt svar är:

Du behöver börja med att skriva din manual på rätt sätt, annars spelar det ingen roll vilken metod du väljer. Vattenfallsdokumentation kan inte följa en agil process, oavsett verktyg.

Jämför med ett husbygge:

Du tillför inget värde om du sätter upp en dyr designertapet på en fallfärdig vägg. Du måste först fixa stommen.

På samma sätt behöver du först skapa en välskriven och strukturerad manual för få någon nytta av både agila processer och kraftfulla verktyg.

 

Tänk tetris!

Tänk dig att du har ett gäng tetris-bitar att arbeta med. Vad tror du blir lättast att kombinera? Stora sjok som de röda, eller små, enhetliga bitar som de blå?

De blå bitarna kan du snabbt och lätt lägga till fler av, allt eftersom din produkt utvecklas. Du kan jobba iterativt. Du kan snabbt ta bort bitar som inte är uppdaterade. Och bitarna passar in på många olika ställen. 

Hur låter det om du översätter det till manual och information om din produkt?

Är din dokumentation i stora sjok, där det är svårt att plocka ut och flytta runt delar? I så fall är det kanske dags tänka om. 

Modulär och strukturerad information

Nyckeln till flexibilitet är struktur. 

Ta en titt på din befintliga manual (eller tjuvkika på någon annans). Titta på lägsta rubriknivån:

  • Hur tydligt strukturerat är innehållet i texten under?
  • Innehåller texten fler än en idéer?
  • Hur väl stämmer rubriken med innehållet?
  • Vilken typ av information är innehållet? Instruktion eller fakta?

Ju mer stringent innehållet är, desto lättare är det att uppdatera, återanvända och hitta i informationen. 

Låter det flummigt? Låt mig visa exempel.

Exempel på modulär dokumentation

Det här är ett ganska vanligt och, låt oss säga, traditionellt sätt att skriva på:

Allt i texten ovan handlar visserligen om formatmallar. Men det är fakta och instruktioner blandat huller om buller. Dessutom finns hela tre idéer i texten:

  • syftet med formatmallar
  • hur man använder formatmallar
  • hur man ändrar på formatmallar.

Ett mer strukturerat sätt att skriva på är att bryta isär texten så att fakta (i det här fallet syftet) står för sig, och instruktionerna var för sig:

Och ja, det kanske tar mer plats, men å andra sidan kan du återanvända de här blocken på olika ställen. De är väl avgränsade. De kan då få en tydlig rubrik, vilket gör att användaren inte behöver läsa text i onödan.

Det blir också lättare för dig  eller någon annan  att uppdatera.

Ser du också hur du enkelt kan lägga till ytterligare block med tiden, utan att påverka den befintliga texten? Eller tillfälligt ta bort block som du inte hinner uppdatera just nu. Du kan sedan iterativt lägga tillbaka dem när du hunnit uppdatera.

Och vips har du en agil dokumentation.

Vill du läsa mer om agil dokumentation?

Här kan du se mitt blixttal om agil dokumentation från Agila Sverige 2019:

Agil dokumentation en oxymoron?

Och här är två andra tips:

Agil dokumentation tips #2: scope och detaljnivå

Agil dokumentation tips #3: Den vanliga utvecklarmissen

 

Vill du lära dig mer?

I min webbkurs får du lära dig en systematisk metod för att skriva manual. Det gör manualen lättare att skriva, lättare att läsa och lättare att uppdatera.
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

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

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

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.