Documentatienormen om je aan te houden

De normen die je volgt, zijn afhankelijk van het soort documentatie dat je opstelt. Hieronder een aantal veelvoorkomende soorten, evenals suggesties voor sjablonen die je kunt gebruiken om je normen vast te stellen.

Elk project verloopt soepeler als alle betrokkenen op één lijn zitten. Alle teamleden van een project hebben een enige bron van waarheid nodig dat ze op elk moment kunnen raadplegen. Zonder een gedocumenteerd projectplan kunnen teamleden het grote geheel uit het oog verliezen en daardoor tijd verspillen.

Je kunt deze sjabloon van Confluence gebruiken om de projectdocumentatie te versnellen en te standaardiseren. Hierdoor kun je consistent belangrijke informatie over elk project vastleggen.

Zijn je teamleden tijd kwijt omdat ze continu aan anderen moeten uitleggen hoe ze taken moeten uitvoeren? Of ben je wel eens in paniek geraakt toen de enige persoon die wist hoe een belangrijke taak of proces uitgevoerd moest worden er niet was?

Uit deze scenario's blijkt het belang van instructiedocumentatie. Alles wat je teamleden herhaaldelijk doen, moet worden gedocumenteerd op een manier die iedereen in je team kan gebruiken om die taak of dat proces te voltooien.

Instructiedocumentatie is effectiever, en veel gemakkelijker om op te stellen als je normen hebt vastgesteld. Hierbij komt een sjabloon wederom goed van pas. De sjabloon van Confluence voor instructie-artikelen bevat bijvoorbeeld een formule voor procesdocumentatie.

Documentatie voor software en andere technische producten kan uitleggen hoe het product werkt, hoe het moet worden gebruikt, hoe het is gemaakt en hoe het is samengesteld.

Softwareteams kunnen documentatie naslaan voor productvereisten, releasenotes of ontwerpspecificaties. Technische teams kunnen documentatie gebruiken om code, API's te beschrijven en hun softwareontwikkelingsprocessen vast te leggen.

Technische documentatie is vaak lang en gedetailleerd, en wordt regelmatig bijgewerkt. Daarom is het vooral belangrijk om over de juiste tools te beschikken om nauwkeurigheid te garanderen en tijd te besparen. Je kunt bijvoorbeeld bestaande sjablonen in Confluence gebruiken of je eigen sjablonen aanmaken. Confluence heeft ook macro's waarmee je gemakkelijk tekst bijwerkt of hergebruikt.

Het maakt niet uit wat voor soort documentatie je maakt. Er zijn een paar belangrijke vaardigheden die zorgen dat je werk aan je documentatienormen voldoet en nuttig is voor gebruikers.

• Ordening. Weten welke informatie je wilt documenteren is slechts het begin. Je moet de informatie ook op een gemakkelijk te volgen manier presenteren. Naast het ordenen van de informatie in een logische volgorde, is het ook belangrijk om elementen zoals titelpagina's en lijsten met opsommingstekens te gebruiken om de lezers te leiden.
• Duidelijkheid. Als je duidelijke, eenvoudig te begrijpen documentatie wilt, heb je precies het juiste detailniveau nodig. Te weinig informatie is verwarrend, maar dat geldt ook voor teveel informatie. Je kunt documentatie verduidelijken door bijvoorbeeld aandacht te besteden aan je grammatica, jargon te vermijden en specifieke woorden te gebruiken in plaats van vage woorden (zoals 'vaak').
• Consistentie. Aandacht besteden aan consistentie is een van de nuttigste dingen die je kunt doen voor de lezers van je documentatie. Een gebruiker zal het bijvoorbeeld gemakkelijker vinden om je instructiedocumentatie te volgen als deze dezelfde indeling heeft als de andere instructiedocumenten binnen je organisatie.

Het vaststellen van normen leidt niet alleen tot betere documentatie. Je kunt die documentatie hierdoor ook effectiever verspreiden.

Documentatie moet toegankelijk zijn voor je hele team, anders heeft deze geen nut. Je wilt niet dat teamleden belangrijke informatie op hun individuele harde schijf opslaan. En je wilt niet dat ze moeten vertrouwen op één afgedrukt document dat verborgen ligt in een willekeurige archiefkast. Situaties zoals deze leiden tot verwarring en inefficiëntie.

Teamleden die verschillende versies van documentatie gebruiken, kunnen bijvoorbeeld een miscommunicatie hebben of elkaar per ongeluk extra werk bezorgen. Of iemand die op afstand werkt, heeft mogelijk toegang nodig tot documentatie waarvan alleen een fysieke kopie op kantoor bestaat.

Je kunt deze problemen voorkomen door het opslaan en verspreiden van documentatie te standaardiseren. Dit doe je het beste aan de hand van een centrale repository: één plek waar alle medewerkers de meest actuele informatie kunnen vinden. Maar naast alles op één plek krijgen, moet je er ook voor zorgen dat medewerkers op die plek gemakkelijk kunnen vinden wat ze zoeken.

Voor ons bij Atlassian is die centrale repository Confluence. Functies zoals een krachtige zoekfunctie, een overzichtelijk paginaoverzicht en een pagina-archief zorgen ervoor dat content altijd gemakkelijk te vinden, binnen handbereik en actueel is.

In Confluence heeft elk team of project een space waarin de gerelateerde documentatie geordend kan worden. Teamleden kunnen een hiërarchie van pagina's aanmaken om alle informatie in het paginaoverzicht geordend en zichtbaar te houden. Medewerkers kunnen spaces of subpagina's bekijken die relevant zijn om op de hoogte te blijven wanneer content wordt gewijzigd. Als je een bepaalde space of pagina wilt verspreiden, kun je de deelknop of commentaar op een pagina gebruiken en andere teamleden taggen. Alle geopende pagina's in Confluence kunnen door andere medewerkers gevonden worden en ze kunnen filters gebruiken om hun zoekopdracht te verfijnen op auteur, publicatiedatum of space.

Niet alleen je afzonderlijke documentatie moet regelmatig bijgewerkt worden, dit geldt ook voor het systeem waarmee documentatie ingediend en geordend wordt. Vergeet dus niet om hier ook normen voor vast te stellen. Hoe vaak moet je je documentarchivering opnieuw bekijken en opruimen? Zet die momenten maar direct op de kalender.

Nu je een overzicht hebt van documentatienormen, kun je richtlijnen opstellen of herzien voor de soorten documentatie die je team nodig heeft. De tijd die je investeert in deze normen, helpt je om sneller documentatie op te stellen en die documentatie nuttiger te maken voor je team.