Lättillgänglig dokumentation som också är lätt att ta till sig är viktigt för att arbetet som systemutvecklare ska vara effektivt. Lättillgänglig betyder att dokumentationen ska finnas där den behövs eller i en central sökbar databas. För att vara lätt att ta till sig bör dokumentationen vara genomtänkt och grundläggande, tänk ”vad, hur och varför” för att sedan lämna avancerade delar till fördjupning.

Dokumentation för att hjälpa

Dokumentation är en av utvecklarnas viktigaste hjälpmedel under arbetet, till exempel vid utveckling av en ny funktion, vid felsökning eller för att kunna ge korrekt support. Om dokumentationen är välgjord och lättillgänglig kan den i bästa fall förebygga support. Nedan följer två exempel där utvecklare får ett enklare arbete med hjälp av bra dokumentation.

I det första exemplet är uppdraget att skapa en integration mellan två system så att de kan kommunicera. För att det ska fungera friktionsfritt behövs regler för hur systemen ska kommunicera. Reglerna behöver vara dokumenterade, tillgängliga, aktuella och enkla att ta till sig. Oftast uppfyller dokumentationen endast den förstnämnda, att det är dokumenterat.

En ”kom igång”-guide är ett ypperligt sätt att börja på, ett ”Hello world”* för alla

En PDF på 120 sidor med löpande text, som det tar en vecka att ta sig igenom och förstå, låter som ett bra uppslagsverk. Men för att få en uppfattning om projektets komplexitet, och vilka resurser som kommer behövas, är det bättre med en enklare sammanfattning. Då kan en ”kom-gång-guide” vara ett ypperligt sätt att börja på. Är dokumentationen på en bra nivå från början blir det också enklare att hålla den uppdaterad och aktuell. Hur omfattande dokumentationen behöver vara kan variera; att byta typsnitt i Word till exempel, är något som de flesta känner till och det behöver därför inte dokumenteras i detalj. Men för att tekniken ska adopteras på bred front utan dåliga implementationer, till exempel att ditt macro blir fel, behövs det lättillgänglig och tydlig dokumentation på mer avancerade funktioner. Annars kan användaren köra fast, bli frustrerad och kanske börja leta efter produkter som är bättre dokumenterade.

[1] Macros i word

Några tips på hur bra dokumentation kan se ut:

• Gör en kom igång-guide, summera vad, hur och varför, ett ”Hello world[2]" för alla
• Spara detaljerna till en handbok på avancerad nivå
• Gör dokumentation riktad mot både era kunder och era medarbetare
• Låt den vara lättillgänglig (läs mer i detta blogginlägg)

[2] ”Hello world”-avsnittet är ofta den första guiden man ser inom programmering när man ska börja använda ett större ramverk. Avsnittet innehåller det mest grundläggande och endast det man behöver veta för att komma igång och få en första förståelse för ramverket. Utifrån den grunden kan man sedan fortsätta att bredda sin kunskap. Exempel: www.mkyong.com/html/html-tutorial-hello-world/. Exempel för att skapa en steg-för-steg-guide i InfoCaption.

Tillgänglig dokumentation med mening

I det andra exemplet är uppdraget att felsöka en funktion i ett system. Här behövs dokumentation för att utvecklaren, på ett enkelt och mindre tidskrävande sätt, ska veta vad alla bitar kod har för syfte. Denna typ av dokumentation brukar oftast finnas direkt i koden, men för att få en bättre bild av helheten är det bra med dokumentation som förklarar syftet med funktionen man felsöker. Varför finns funktionen från början? Vad levererar den för värde till användaren? På så vis kan utvecklaren enkelt få reda på vad funktionen borde göra, var det kan gå fel, åtgärda felet och kontrollera att funktionen fungerar som den ska. Dokumentation för detta har inte en naturlig plats i källkoden och för en veteran i organisationen är det kanske självklart vad funktionen har för syfte i systemet ändå. Vi är dock inte alla veteraner och dokumentationen bör anpassas för alla.

Om syftet med funktionen tydligt kan kopplas till en plats i systemet där den används av en slutanvändare, bör dokumentationen också finnas på samma plats, direkt i klartext eller via en länk. Mer utförlig dokumentation kan finnas tillgänglig i en handbok som beskriver flera funktioner i systemet och mer ingående detaljer. Vanligtvis finns dessa handböcker men är då skapade utifrån ett kundperspektiv snarare än som dokumentation för en utvecklare. Ge skapandet av handböckerna lite extra tid så att de även passar era medarbetare. Bonusen i det blir att kunderna även kan få tillgång till fördjupning om så önskas.

Avslutande ord

Det här var två mer specifika exempel i en utvecklares vardagskamp för bättre dokumentation, men det finns givetvis många tillfällen där det kan göra arbetet mer effektivt. Nytillkomna i en organisation har ofta många funderingar kring hur olika delar i arbetet ser ut. Hur ser organisationens rutiner ut för ärendehantering, testning, kodgranskning och release? Vad händer när rutiner ändras?  Eller något så grundläggande som: Hur får jag tillgång till koden?

Att spara all dokumentation i en central databas som gör den sökbar och tillgänglig när den behövs gör den även lätt att uppdatera.

För att dokumentationen som är aktuell för ditt arbete ska bli mer tillgänglig och användbar kan ni i organisationen ställa er dessa tre frågor:

• Är dokumentationen lätt att nå för dem som behöver den?
• Är den lätt att ta till sig?
• Håller ni den uppdaterad?

Vill du lära dig mer?