Lett tilgjengelig dokumentasjon på et nivå som er lett å ta til seg er viktig for at arbeidet som systemutvikler skal være effektivt. Med lett tilgjengelig mener jeg at dokumentasjonen skal finnes der det er behov for den, eller i en sentral søkbar database. For å være lett å forstå bør dokumentasjonen være gjennomtenkt og ved første øyeblikk være grunnleggende – tenk ”hvorfor, hva og hvordan” for å deretter etterlate mer avanserte deler til videre lesning.

Dokumentasjon for å hjelpe

Dokumentasjon er et av utviklernes viktigste hjelpemidler under arbeidet. Jeg som er utvikler, dokumenterer og trenger dokumentasjon når jeg f.eks. utvikler en funksjon som skal brukes av mange sluttbrukere. Jeg trenger også dokumentasjon når jeg feilsøker en funksjon for å se hvor puslespillet ikke går opp eller for å kunne gi god og korrekt support. Er dokumentasjonen godt gjort og er lett tilgjengelig kan den i beste fall forebygge support. Jeg har to eksempler på tilfeller der jeg som utvikler får et lettere arbeid med hjelp av god dokumentasjon.

I det første tilfellet var oppdraget å skape en integrasjon med et annet system slik at systemene kunne kommunisere. For at det skal gå smidig trengs det regler for hvordan man skal kommunisere mellom systemene. Reglene bør være dokumentert, tilgjengelige, aktuelle og enkle å ta til seg. Som oftest oppfyller dokumentasjonen bare de førstnevnte, at det er dokumentert.

En ”kom i gang”-guide er en ypperlig måte å starte på… …”Hello world” for alle

En PDF på 120 sider med løpende tekst som det tar en uke med store doser kaffe å ta seg igjennom og forstå høres ikke ut som et godt oppslagsverk. For å få en generell oppfattning om projektets kompleksitet og hvilke ressurser som kommer til å trengs på en sunnere måte er det nødvendig med et enklere sammendrag. En ”kom igang”-guide er en ypperlig måte å begynne på. Om dokumentasjonen holder et godt nivå fra begynnelsen blir den også enklere å oppdatere og holde aktuell. Enkel og lett tilgjengelig dokumentasjon blir mer vanlig i takt med at de tekniske delene blir mer og mer abstrakte. Bytte av font i Word er for eksempel bytte noe de fleste kjenner til og trenger derfor ikke dokumenteres i detalj. Å lage makroer i Word ([1] ) er derimot ikke like almenn kjent og trenger god dokumentasjon. For at teknikken skal adopteres på bred front uten dårlige implementasjoner, for eksempel at din makro blir feil, trengs det lett tilgjengelig og tydelig dokumentasjon på disse mer avanserte funksjonene. Ellers kan brukerne sette seg fast, bli frustrert og kanskje heller lete frem produkter som er bedre dokumenterte.

[1] Macros i word

Noen tips til hvordan en god dokumentasjon kan se ut:

• Lag en kom igang-guide, tenk: oppsummere hvorfor, hva og hvordan, ”Hello world[2] for alle”
• Lagre detaljene til en håndbok på avansert nivå
• Gjør både dokumentasjon rettet mot deres kunder og mot medarbeiderne
• La den være lett tilgjengelig (les mer i dette blogginnlegget)

[2] ”Hello world”-avsnittet er ofte den første guiden man ser i programmering når man skal begynne å bruke ett større rammeverk. Det avsnittet inneholder det mest grunnleggende og bare det man trenger å vite for å komme i gang og få en første forståelse for rammeverket. Ut fra det grunnlaget kan man siden fortsette å utvide sin kunnskap. Eksempel: www.mkyong.com/html/html-tutorial-hello-world/. Eksempel for å lage en steg-for-steg-guide i InfoCaption.

Tilgjengelig dokumentasjon med mening

I det andre tilfellet er oppdraget å feilsøke en funksjon i et system. Her trengs dokumentasjon for at utvikleren på en enkel og mindre tidskrevende måte skal vite hva alle biter kode har for formål. Denne typen av dokumentasjon pleier å finnes direkte i koden. Det er bra, men for å få et bedre bilde av helheten er det bra med dokumentasjon som forteller hva funksjonen som feilsøkes gjør i systemet. Hvorfor finnes funksjonen i utgangspunktet? Hva leverer den for verdi for brukeren? På den måten kan utvikleren enkelt få greie på hva funksjonen burde gjøre, hvor det kan tenkes å gå feil, rette opp feilen og kontrollere at funksjonen fungerer som den skal. Dokumentasjon for dette har ikke en naturlig plass i kildekoden og for en veteran i organisasjonen er det kanskje åpenbart hva funksjonen gjør i systemet, men vi er ikke alle veteraner.

Om poenget med funksjonen tydelig kan kobles til et sted i systemet der den brukes av en sluttbruker bør den også finnes på samme sted, direkte i klartekst eller via en lenke. Mer utførlig dokumentasjon kan i stedet legges i en håndbok som beskriver flere funksjoner i systemet og mer inngående detaljer. Disse håndbøkene finnes som regel, men er skapt ut fra et kundeperspektiv mer enn som dokumentasjon for en utvikler. Ta noen minutter ekstra og tenk på at disse ikke bare er bra for deres kunder, men også for deres medarbeidere. Det kommer også til å ende opp som en bedre dokumentasjon for spørrende kunder.

Avsluttende ord

Dette var to mer spesifikke deler i en utviklers hverdagskamp mot bedre dokumentasjon. Det finnes enda flere tilfeller der god dokumentasjon gjør det daglige arbeidet mer effektivt for en systemutvikler. Nyankommende til organisasjonen har ofte mange spørsmål rundt hvordan ulike deler i arbeidet ser ut. Spørsmål som f.eks: ”Hvordan ser organisasjonens rutiner for ærendehåndtering, testing, kodegransking og release ut?”, ”Hva hender når rutiner endres?” eller noe så grunnleggende som ”hvordan kommer jeg igang og får tilgang til koden?”.

Å spare all dokumentassjon i en sentral database som gjør den søkbar og lett tilgjengelig når den trengs gjør den også lett å oppdatere. 

For at dokumentasjonen som er aktuell for ditt arbeid skal bli mer tilgjengelig burde dere stille dere selv tre spørsmål:

• Er dokumentasjonen lett å nå for de som trenger den?
• Holder dere den oppdatert?
• Er den lett å ta til seg?

Vil du lære mer?