Maatwerksoftware heeft geen handleiding op internet. Er is geen forum waar andere gebruikers je vraag al stelden, geen leverancier met een kennisbank over jouw systeem. Alles wat erover te weten valt, zit in de code en in de hoofden van de mensen die hem ontwikkelden. Documentatie is de enige plek waar die kennis bewaard blijft als die mensen vertrekken.
Dat maakt documentatie bij maatwerk geen administratieve bijzaak, maar onderdeel van het product. Ze bepaalt of je systeem over vijf jaar nog aanpasbaar is, hoe snel een nieuw teamlid meedraait en vooral of je als eigenaar zelf kunt kiezen wie eraan verder werkt.
Documentatie bepaalt hoe afhankelijk je bent
Bij standaardsoftware kun je altijd terugvallen op de leverancier, met handleidingen, een supportafdeling en een gemeenschap van gebruikers. Bij maatwerk bestaat die externe bron niet. Verdwijnt de kennis, dan is reverse-engineeren de enige weg terug: uit de code reconstrueren wat het systeem doet. Dat kan, maar het is traag, kostbaar en foutgevoelig.
Een ongedocumenteerd systeem bindt je in de praktijk aan de partij die het ontwikkelde, ook als de samenwerking daar geen aanleiding meer toe geeft. Goede documentatie is daarmee een vorm van eigenaarschap, net als het bezit van je broncode. Hoe je dat eigenaarschap contractueel regelt, lees je in ons artikel over het voorkomen van vendor lock-in.
Vier lagen, elk met een eigen lezer
Goede documentatie is geen dik document dat alles beschrijft, maar een set dunne lagen die elk hun eigen lezer bedienen.
- Gebruikersdocumentatie: hoe eindgebruikers en beheerders hun dagelijkse taken in het systeem uitvoeren.
- Technische documentatie: de architectuur, de datastructuur en de manier waarop je het systeem draait en uitrolt, voor ontwikkelaars.
- API-documentatie: hoe andere systemen koppelen, welke gegevens beschikbaar zijn en in welke vorm.
- Beslisdocumentatie: waarom keuzes zo zijn gemaakt, van bedrijfsregels tot de afwegingen daarachter.
Die laatste laag wordt het vaakst overgeslagen en het hardst gemist. Wat een systeem doet, valt desnoods uit de code af te lezen. Waarom het dat zo doet, niet.
Zo houden wij klanten onafhankelijk van onszelf
Bij eenvoud behandelen we documentatie als onderdeel van het systeem zelf. Ze staat in dezelfde repository als de broncode, zodat een wijziging aan de software en de bijbehorende beschrijving samen worden beoordeeld en samen worden opgeleverd. Verouderde documentatie valt dan net zo op als een fout in de code.
De maatstaf die we hanteren is overdraagbaarheid: een ontwikkelteam dat het systeem nooit eerder zag, moet met broncode en documentatie zelfstandig verder kunnen. Daarom hoort bij een oplevering een beschrijving van hoe je het systeem lokaal draait, hoe een release verloopt, waar de koppelingen zitten en welke keuzes bewust zo zijn gemaakt. Niet omdat we verwachten dat klanten vertrekken, maar omdat software die alleen de oorspronkelijke ontwikkelaar kan onderhouden geen goed product is. We hebben genoeg systemen langer zien meegaan dan het team dat ze ontwikkelde om te weten dat overdraagbaarheid vroeg of laat nodig is.
Actueel houden is het eigenlijke werk
Verouderde documentatie is erger dan geen documentatie: ze wekt vertrouwen dat ze niet waarmaakt. Actueel blijft ze alleen als bijwerken deel is van het ontwikkelproces zelf. Een aanpassing is pas af als de beschrijving weer klopt, en wat automatisch uit de code te genereren valt, zoals een API-overzicht, genereer je liever dan dat je het met de hand bijhoudt.
Vraag je softwarepartner daarom niet alleen óf er gedocumenteerd wordt, maar wanneer: tijdens het werk of achteraf. Dat ene antwoord voorspelt hoe bruikbaar de documentatie over een paar jaar is.
Draait er bij jou maatwerksoftware waarvan de documentatie dun of verouderd is? Begin dan niet met alles tegelijk, maar met de plekken waar de meeste kennis op het spel staat: de functies die dagelijks worden gebruikt en de keuzes die niemand meer kan navertellen. Binnen doorontwikkeling en beheer doen we dat geregeld voor systemen die anderen ontwikkelden: eerst doorgronden en vastleggen, daarna pas veranderen.