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 med tydlig sortering
Jo, tänk dig att du står framför ett julbord, en enorm buffé som dignar av olika rätter. Du kan välja dina sillfavoriter men kan skippa brysselkålen om du vill.
Om alla rätter däremot redan vore ihopblandade i en enda gryta skulle allt bli så mycket svårare, både för dig som ska äta och för personalen som ska fylla på med vissa rätter, eller – gud förbjude – ta bort en rätt från julbordet.
Så serveringspersonalen gör det lättare för både sig själva och för kunden genom att hålla alla rätter separata på julbordet. Dessutom brukar personalen sortera rätterna efter kallskuret, varmrätter, salladsrätter och liknande för att ytterligare underlätta ett bra flöde i matsalen. Smart!
Modulära julrecept ger flexibilitet
Kanske är liknelsen med julbord lite långt från dokumentation? Ok, men vi kan prata om receptet på en jultallrik istället. Hur blir det om vi skriver som en enda lång, integrerad text?
(Recepten kommer ursprungligen från Coop, men jag har skrivit om för att de ska passa mina syften.)
Hur blir det om vi delar upp receptet på jultallriken i moduler?
Vissa skulle kanske hävda att den första, långa texten ger ett bättre flöde. Det kan möjligen stämma om kocken vill göra alla rätterna och inget annat.
Men vad händer om kocken bara vill laga den ena rätten? Eller om du som skribent vill lägga till en rätt till på jultallriken? Hur lätt är att det lägga till eller ta bort en rätt i den långa texten jämfört med den modulära texten?
Lättare att anpassa presentationssättet efter innehållet
Med väl avgränsade moduler har du dessutom chansen att presentera informationen på det sätt som passar just den typen av information på bästa sätt. Precis som soppa bäst serveras i skålformat kärl, medan rökt lax är lättare att ta av från ett fat, så är det lättare att få en överblick av ingredienser om de presenteras i en lista istället för i löptext. Tillagningsanvisningarna bör däremot stå i en stegvis instruktion.
Buffé istället för gryta
Så tänk dig din dokumentation som en buffé av information, med väl avgränsade block. Gör det lätt för användaren att ta del av innehållet genom att ta en tydlig och informativ rubrik och genom att presentera informationen på bästa sätt.
Hur ser dina manualer ut? Buffé eller gryta?
Läs mer om modulär dokumentation
