Hvis du skal vælge frit mellem god, dårlig og ikke-eksisterende it-dokumentation, vil du naturligvis vælge god it-dokumentation. Men når du står midt i et it-udviklingsprojekt med manglende resurser og en stram deadline, er der desværre en risiko for, at du ender med ikke-eksisterende it-dokumentation. Kompromisset bliver ofte den dårlige it-dokumentation. Det er den dokumentation, leverandøren eller medarbejderne har brugt tid på at skrive, men som ingen læser, fordi den ikke hjælper dem i deres daglige arbejde.

Mange it-løsninger lider under manglen på god it-dokumentation. Konsekvenserne er ofte store. Det er for eksempel noget nær umuligt at tage de rigtige forretningsmæssige og tekniske beslutninger, hvis indsigten i it-løsningens tilstand er fejlbehæftet eller ufuldstændig.

Det er alt andet lige også dyrere at sende et it-system i genudbud, når tilbudsgiverne må indberegne en væsentlig risiko med i prisen, fordi de ikke er sikre på, hvad de giver tilbud på.

Derfor er der god grund til at investere i den rette mængde af dokumentation af den rette kvalitet, uanset om du som organisation indkøber eller vælger selv at udvikle dine it-løsninger. Jeg giver her fire bud på, hvordan du kommer i gang.

1. Overbevis dig selv 

God it-dokumentation kræver en ikke ubetydelig investering, men desværre bliver omkostningerne i sidste ende endnu større, hvis du lader være. Det er denne ligning, der skal skabe motivationen i ledelsen og organisationen. Lad mig give nogle eksempler på, hvor omkostningerne kan ligge, hvis en it-løsning ikke er ordentligt dokumenteret:

  • Fejlagtige beslutninger pga. manglende indsigt i it-løsningens faktiske tilstand, herunder løsningens design, kodekvalitet, teknologiplatform, værktøjsunderstøttelse, kendte fejl, udestående funktionalitet osv.
  • Fordyrende genudbud af it-løsningen, når tilbudsgiverne må indberegne en væsentlig risiko med i prisen, fordi de ikke er sikre på, hvad de giver tilbud på. Læs om, hvordan du sikrer et konkurrencedygtigt udbud her.
  • Ineffektiv oplæring af nye medarbejdere, fordi viden kun overleveres mundtligt.
  • Ineffektive og inkonsistente arbejdsgange, fordi medarbejderne derfor må gætte sig frem (hvad enten de bruger, drifter eller vedligeholder it-løsningen).
  • Uønsket afhængighed af de få nøglemedarbejdere, der har det hele i hovedet (hvad enten de sidder i organisationen eller hos leverandøren).
  • Langstrakte compliance-, integrations- eller migreringsprojekter, fordi den nødvendige viden ikke findes på skrift.

Der er mange forretningsmæssige aktiviteter, der tager længere tid og fører til dårligere resultater, hvis it-løsningerne ikke har den rette dokumentation af den rette kvalitet. Alligevel kan det være svært at tage beslutningen om at investere nok i it-dokumentation, for som regel går det jo fint uden. Men hvis du gerne vil være bedre end ”det går jo nok”, så må og skal dokumentationsarbejdet tages alvorligt som en strategisk kapabilitet.

2. Muliggør succesen for dine medarbejdere 

Hvis du vil have dine leverandører eller medarbejdere til at skrive god it-dokumentation, skal det være tydeligt, hvad de skal gøre. Hvornår er det en succes? Tager det en time eller en uge? Det er ikke nok, at dokumentationsopgaven bliver tilføjet ”definition of done”, sådan som det kendes fra den agile verden.

Det skal gøres konkret. Et enkelt overskueligt og målrettet dokument er bedre end en stor skabelon, der er omstændelig at fylde ud.

Det skal være realistisk og meningsfuldt. Formålet med dokumentationen skal ikke være, at den stilles på hylden for at se flot ud. Formålet skal være, at den skal bruges af nogen til noget.

Som det fremgår af standarden IEEE 2016-2009 om ”Software Design Descriptions”, skal dokumentation være skrevet, så ”information of interest is captured, organized, presented and disseminated to all interested parties”.

Med andre ord skal dokumentationen tage udgangspunkt i målgruppens behov, som for det meste er ret konkrete. It-udviklerne skal kunne sætte deres udviklingsværktøjer rigtigt op, finde rundt i kildekoden og følge it-løsningens designprincipper, så udviklingsarbejdet kan ske effektivt og med bedst muligt resultat.

Supportafdelingen skal kunne forstå beskederne i overvågningssystemet, så de kan reagere mest hensigtsmæssigt, når it-løsningen fejler. Og de skal kunne tildele de rigtige brugerrettigheder til de rigtige brugere, så it-sikkerheden realiseres gnidningsfrit og på det ønskede niveau.

Målgruppen for dokumentationen skal derfor også kunne stille krav til dokumentationen. Og de skal have ret til afvise den, hvis den ikke er god nok til at hjælpe dem i det arbejde, den netop er tiltænkt at hjælpe dem med.

Hvis dem, der skal anvende dokumentationen, har sagt ja til den, er det mere sandsynligt, at de faktisk læser den og kan bruge den til noget. Samtidig er der mindre tvivl om, at dokumentationen faktisk er blevet færdig i den rette kvalitet og i det rette omfang.

3. Sæt gang i den rigtige adfærd  

”Hvis vi skal ændre menneskers adfærd, skal vi ikke ændre deres holdninger. Vi skal ændre deres handlinger”.

Sådan skriver adfærdsdesigner Morten Münster i bogen ”Jytte fra Marketing er desværre gået for i dag”.

I de fleste organisationer er medarbejdernes handlinger styret ved hjælp af processer, så hvis du ønsker at ændre adfærden omkring dokumentationsarbejdet, er processerne et godt sted at starte.

Nærmere bestemt bør du starte med it-udviklingsprocesserne, fra idéfase til gennemførsel og realisering. Det er nemlig her, at it-løsningen både skabes, ændres og vedligeholdes, og hvis dokumentation skal afspejle it-løsningen, bør den ændres i takt med ændringerne i det, den skal afspejle. Det er der intet nyt i, men en væsentlig vanskelighed ved udarbejdelse af it-dokumentation er, at det ikke sker alligevel.

Fordi kravene til dokumentation ofte er uklare (jf. punkt 2), og fordi det mange gange kan være svært at se værdien i det store arbejde med at skrive dokumentationen (jf. punkt 1), har dokumentationsarbejdet en tendens til at ”skifte mod højre” i it-udviklingsprocessen.

Resultatet bliver, at dokumentation først skrives til allersidst, når der ikke er mere tid, og når betydelige dele af den vigtige viden om it-løsningen efterhånden er gået i glemmebogen.

Løsningen er at ”skifte mod venstre” og få stillet tydelige og meningsfulde krav til dokumentationen så tidligt som muligt. Kun når kravene til dokumentationen er med fra starten, bliver det muligt at sidestille dem med de øvrige krav, og dermed bliver det muligt at prioritere, planlægge, estimere, udføre, følge op på og ”teste” (dvs. lave review og godkende) dem i løbet af hele it-projektforløbet.

Du får, hvad du beder om, og derfor er det vigtigt at bede om den rigtige dokumentation så konkret og tydeligt som muligt.

4. Læg en langsigtet plan 

Ovenstående tiltag vil kunne løfte kvaliteten af din it-dokumentation betydeligt, men de kræver en investering, der ligger ud over opgaven med at skrive selve dokumentationen. Derfor er det også urealistisk at forvente, at denne investering kan bæres af de enkelte it-projekter.

Derimod må tiltagene betragtes som en strategisk investering i tværgående kapabiliteter, der ligger forud for de it-projekter, der skal understøttes.

Sådanne kapabiliteter inkluderer:

  • Et katalog af dokumenttyper, deres formål, målgruppe og indhold, som normalt forventes at være hensigtsmæssige for de it-løsninger, der indkøbes eller udvikles af organisationen.
  • En udbygning af eksisterende it-processer med detaljerede og letforståelige trin (eller tjekpunkter), som sætter krav til dokumentationsarbejdet; for eksempel skal det tidligt i forløbet beskrives, præcis hvilken dokumentation der skal leveres sammen med it-løsningen, og hvornår den skal leveres.
  • Vejledninger, undervisning og evt. en tværgående støttefunktion, der kan stille rådgivning, kompetencer og kvalitetskontrol til rådighed for de enkelte it-projekter.
  • Værktøjer til brug for arkivering, versionering, adgangskontrol, backup, registrering af review-kommentarer m.v.

Kapabiliteterne kan med fordel opstilles i en modenhedstrappe, der muliggør en realistisk og langsigtet opbygning af organisationens samlede formåen i forhold til dokumentationsarbejdet. Visse kapabiliteter vil naturligt ligge forud for andre, som af samme grund kræver en større grad af modenhed, før de realiseres.

Konklusion

Uanset om man som organisation indkøber eller selv vælger at udvikle sine it-løsninger, er god it-dokumentation et vigtigt element i den fortsatte brug, drift, vedligeholdelse og videreudvikling af it-løsningerne på både kort og langt sigt. Uden god it-dokumentation er der høj risiko for, at fordele og gevinster ikke opnås i det tilsigtede omfang, eller at omkostningerne bliver for høje. Derfor bør du i din organisation investere i at opbygge evnen til at kravstille og fremstille den rette dokumentation af rette omfang på linje andre strategiske kapabiliteter.