Lättillgänglig dokumentation som är på en nivå som ä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 vid första anblick vara grundläggande, tänk ”varför, vad och hur” för att sedan lämna avancerade delar till fördjupning.

Dokumentation är en av utvecklarnas viktigaste hjälpmedel under arbetet. Jag som utvecklare dokumenterar och är i behov av dokumentation när jag till exempel utvecklar en ny funktion som ska användas av mängder med användare. Jag är också i behov av dokumentation när jag felsöker en funktion för att se var pusslet inte går ihop eller för att kunna ge bra och korrekt support. Är dokumentation bra gjord och är lättillgänglig kan den i bästa fall förebygga support. Jag har två exempel på fall där jag som utvecklare får ett enklare arbete med hjälp av bra dokumentation.

Dokumentation för att hjälpa

I det första fallet är uppdraget att skapa en integration med ett annat system så systemen kan kommunicera. För att det ska gå smidigt till behövs det regler för hur systemen ska kommunicera med varandra. Reglerna behöver vara dokumenterade, tillgängliga, aktuella och enkla att ta till sig. Oftast uppfyller dokumentationen endast de förstnämnda, att det är dokumenterat.

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

En PDF på 120 sidor med löpande text som det tar en vecka med stora doser av kaffe att ta sig igenom och förstå låter som ett bra uppslagsverk. Men för att på ett hälsosammare sätt få en generell uppfattning om projektets komplexitet och vilka resurser som kommer behövas är de nödvändigt med en enklare sammanfattning. En ”kom igång”-guide är ett ypperligt sätt att börja på. Om dokumentationen är på en bra nivå från början blir den också enklare att uppdatera och hålla aktuell. Enkel och lättillgänglig dokumentation blir mer vanlig i takt med att det tekniska delarna blir mer och mer abstraherade. Att till exempel byta typsnitt i Word är något som de flesta känner till och behöver därför inte dokumenteras i detalj. Att göra macros i Word[1] däremot är inte lika allmänt känt och behöver bra dokumentation. 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å dessa mer avancerade funktioner. Annars kan användarna köra fast, bli frustrerad och kanske hellre letar sig produkter som är bättre dokumenterade.

[1] Macros i word

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

• Gör en kom igång guide, tänk: summera varför, vad och hur, ”Hello world[2] för alla”
• Spara detaljerna till en handbok på avancerad nivå
• Gör både dokumentation riktad mot era kunder och mot 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. De avsnittet innehåller de mest grundläggande och endast de 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 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 fallet ä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. Det är bra, men för att få en bättre bild av helheten är det bra med dokumentation som berättar vad funktionen som felsöks uppfyller för syfte i systemet. 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 de kan tänkas 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, men vi alla är inte veteraner.

Om syftet med funktionen tydligt kan kopplas till en plats i systemet där den används av en slutanvändare bör den också finnas på samma plats, direkt i klartext eller via en länk. Mer utförlig dokumentation kan istället läggas i en handbok som beskriver flera funktioner i systemet och mer ingående detaljer. Dessa handböcker finns oftast men är skapade utifrån ett kundperspektiv än en dokumentation för en utvecklare. Ta några minuter extra och tänk på att dessa inte bara är bra för era kunder utan även för 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 delar i en utvecklares vardagskamp mot bättre dokumentation. Det finns ännu flera fall där bra dokumentation gör det dagliga arbetet effektivare för en systemutvecklare. Nytillkomna till organisationen har ofta många funderingar kring hur olika delar i arbetet ser ut. Frågor som till exempel: ”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 man kommer jag igång och får tillgång till koden?”.

Samma guide har sedan uppdaterats allteftersom systemet har utvecklats och har använts flera gånger av både mig och flera nytillkomna i företaget

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. Jag minns när jag började på InfoCaption, jag fick uppdraget att förändra videospelaren i systemet. I uppdragsbeskrivningen fanns också en guide länkad som berättade hur jag installerar systemet och hur spelaren fungerade. Några timmar senare var jag redo att leverera min lösning. Samma guide har sedan uppdaterats allteftersom systemet har utvecklats och har använts flera gånger av både mig och flera nytillkomna i företaget. Att återanvända är något som är effektivt inom systemutveckling och likaså inom dokumentation.

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 dom som behöver den?
• Håller ni den uppdaterad?
• Är den lätt att ta till sig?