Hur man skriver bra dokumentation

Med denna analogi i åtanke insåg jag hur viktigt det är att skriva bra dokumentation. Även om vi idag har ett bra arbetsflöde för dokumentering så strävar vi alltid efter att bli bättre så jag började också fundera på hur vi kan förbättra befintlig dokumentation och hur man kan skriva den ännu bättre i framtiden.

Det finns två olika dokumentationer som jag anser att man bör skriva, en för kunden och en för utvecklaren.

Dokumentation för kunden

På vilket sätt kan vi bäst lära våra klienter hur systemet fungerar och hur man arbetar med det? Ett första steg är att ha en användarmanual som introducerar systemet och de funktioner som en klient arbetar med på en daglig basis. Den bör besvara enkla frågor som hur man loggar in, skriver innehåll, men också hur systemet fungerar och hur man bäst använder det.

På Kodamera använder vi främst Drupal (ett CMS) som har en grundläggande manual som vi översatt och som vi använder som grund för att lära våra kunder systemet.  Då varje webbplats som byggs anpassas efter kundens behov behöver även detta dokumenteras.

• Hur använder man systemet bäst?
• Vad har det för begränsningar?
• Arbetsflöden

Hur saker och ting ska fungera kommer man oftast fram till i sprintplaneringar och tidiga diskussioner med kunden, och om man använder det som grund för sin dokumentation kommer man underlätta för sig själv inför framtiden. De tre frågorna listade ovan anser jag vara det mest centrala att besvara och det är mycket sannolikt att man redan har besvarat dessa under diskussionens gång.

För många av våra kunder sätter vi ihop screencasts (filmklipp) där vi  förklarar och framför allt visar hur olika funktioner fungerar och används på våra kunders webbplatser. Det är en typ av dokumentation som är mycket uppskattad. En klar fördel är att kunden kan följa flödet från start till slut och hoppa fram och tillbaka vilket är svårare att få till bra i text. Att skapa nya screencasts i samband med att man släpper nya funktioner anser jag skulle vara riktigt bra.

Vi brukar också bjuda hit våra kunder i några timmar för att introducera dem till det system vi byggt och för att svara på frågor som kan dyka upp. Det är mycket  uppskattat och jag tror att detta är nog ett av de bästa sätten att lära sina kunder hur man arbetar med deras beställda webbplats. Har man inte möjlighet att träffas kan man fortfarande anordna detta via Skype eller Google Hangout. Man kan även se på möjligheten att spela in dessa sessioner så att man kan titta tillbaka vid behov.

Dokumentation för utvecklarna

Då och då behöver man gå tillbaka och arbeta med ett gammalt system som har byggts för många år sedan. Det kan vara en åtgärd som upptäcks eller ny funktion som behöver utvecklas.  Det finns ett koncept inom programmering som kallas technical debt vilket innebär att något man skapat tidigare kan påverka tid och kostnad på grund av komplexitet i systemet.  Det är rätt oundvikligt att introducera detta på grund av flera olika faktorer som att systemet och dess syfte förändras, tid, budget och liknande.  I och med detta kan dessa system vara svåra att arbeta med och det finns kanske inga tester att verifiera att de ändringar man gjort inte producerat något annat fel i system.  Det här är dokumentation kommer in i bilden, saker som man gör idag kommer inte vara lika enkelt att förstå om ett halvår eller längre fram.

Vi jobbar aktivt med att refaktorisera den kod som vi skriver/producerar, alltså att vi skriver om delar av koden och förbättrar den. Tyvärr är det inte alltid ett alternativ även om det skulle behövas. Det finns dock inte alltid en budget eller intresse från kunden att att göra så.

För att förebygga dessa problem har vi på Kodamera *Teach leads* som ansvarar för att skriva och hålla den tekniska dokumentation uppdaterad. Vi har en mall som vi använder som grund på de frågor vi behöver ha koll på. De är till exempel

• Projektdetaljer
  - CMS/ramverk som används?
  - Språk och vilken version?
  - Webbhotell?
  - Tech leads?
• Introduktion, en kort introduktion om vad projektet är och vad det gör
• Komma igång, hur installerar man och får igång projektet i en lokal miljö
• Saker som man verkligen bör känna till om systemet
• Systemstruktur
• Produktionsmiljö och backup rutiner
• Saker man bör kontrollera efter en uppdatering av systemet (såvida vi inte har test)
• Sprint beskrivningar (vad vi gjorde och tidigare gjorts i senaste sprintarna)

En av de viktigaste av dessa punkter är Saker som man verkligen bör känna till om systemet. Vad är det som skiljer sig i detta system från ett annat? Är det något man behöver tänka på när man sätter upp en lokal miljö? Exempelvis att en sida delas till Facebook när man publicerar den.  Vi försöker se till att dessa saker är, per automatik avstängt när man jobbar lokalt, men i äldre projekt eller projekt som vi tagit över kan man inte ta det för givet.

Dokumentation kan ibland kännas onödigt, och kanske rentav tråkigt när man sitter och utvecklar och bygger en webbplats, men det är ett nödvändigt ont. Genom korrekt och utförlig dokumentation kan man inte bara ge bättre och snabbare information till kunden och sina kollegor, det är också ett sätt att följa ett projekts utveckling över tid och på ett överskådligt sätt. Min kollega brukar skandera “Dokumentera mera” och jag är faktiskt böjd att hålla med honom, det är något som måste göras.