Zin en onzin van documentatie

Willen jullie meer of minder documentatie?

Minder! Minder! Minder!

De kans dat ik om bovenstaande tekst word aangeklaagd, lijkt me anno 2017 erg klein. Het enthousiasme om documentatie op te leveren is immers tot een nieuw dieptepunt gedaald. En niet alleen door de opkomst van agile – “Working software over Comprehensive documentation”. Ook onder architecten is het nut van documentatie al jarenlang onderwerp van discussie. Een discussie die gevoed wordt, niet alleen door verschillen in inzicht, maar vooral ook door gebrek aan inzicht. Hoog tijd voor wat nuance in de discussie.

Waarom willen we documenteren?

Dit is hopelijk een open deur. Het is het fundament van onze beschaving. Zo geven we kennis door aan de mensen die na ons komen. Het is efficiënt indien er voldoende lezers zijn: Write Once Read Many. Het is ons externe geheugen. Het is het geheugen van een organisatie, in plaats van het geheugen van één individu. Documenteren is on-ge-loof-lijk veel goedkoper en sneller dan elke keer opnieuw het wiel uitvinden. Of, zoals Roland Drijver het ooit uitdrukte: “Dé informatie-vraag is: “Hoeveel wil je afschrijven, en hoeveel wil je leren?”. En last but not least: documenteren kan vereist zijn om redenen van compliancy of kwaliteitsbeheersing.

Het bovenstaande klinkt denk ik best overtuigend. Waarom is er dan discussie? Een legitieme vraag is derhalve:

Waarom willen we niet documenteren?

Daar zijn ook een heleboel redenen voor te geven. Niet allemaal even sterk, en soms meer van psychologische of historische aard, maar bij elkaar ook een overtuigend geheel:

  • Het kost tijd. Tijd van mensen met schaarse kennis, die we liever inzetten voor het produceren van business value op de korte termijn.
  • In moderne Model Driven development omgevingen is er minder behoefte aan extra documentatie. Probleem opgelost, toch?
  • Het kost geld. Tijd is geld, en goede documentatie schrijven vraagt ook om goede vaklui. Die zijn niet goedkoop.
  • Het is eenzaam werk. We vertellen het elkaar al jaren – en ook nog eens terecht: Gij zult communiceren. Gij zult niet in een ivoren toren blijven.
  • Kosten en baten liggen niet in één hand. Tenzij de kpi’s daarop afgestemd zijn, moet ik investeren ten gunste van mijn opvolger. Mijn bonus of de zijne. In geval van uitbesteding of inhuur: documentatie maakt vervolgtrajecten goedkoper, wat niet in het belang is van de aannemer.
  • Documentatie wordt zó weinig gelezen, en veroudert zó snel, dat het wiel opnieuw uitvinden efficiënter is dan documenteren.
  • Documentatie raakt zoek. Een terugvindbaar geheugen organiseren en implementeren is geen sinecure. Indien dat onderschat wordt, leidt dat tot frustratie en voorgaande conclusies.

Bestuurlijk onvermogen

Directie, Managers, projectleiders, product owners. Als je ze vraagt of documentatie belangrijk is, zullen ze allemaal het politiek gewenste antwoord geven. En dus staat het in onze plannen, definition of done en user stories. En toch, het schiet erbij in, elke keer weer. Het volgende project wacht immers weer?

Het is niet per sé te kwader trouw of onvermogen om te plannen, of een visie op wendbaarheid. Het is in mijn ogen in de eerste plaats bestuurlijk onvermogen. De meeste organisaties die op enige schaal software ontwikkelen of gebruiken, hebben behoefte aan documentatie, maar slagen er niet in om het zó te organiseren dat het niet sneuvelt in de waan van alle dag.

Effective documentation over Continuous discovery

Als architect heb ik dit al zo vaak meegemaakt, dat ik inmiddels wel geleerd heb wat wel werkt en wat niet. Voor organisaties die staan voor kwalitatief goede informatievoorziening, en die echt wendbaar willen zijn, heb ik daarom enkele richtlijnen die écht het verschil kunnen maken:

  1. Software developers schrijven geen architectuur-documentatie.

Hoe vaak worden projectleiders, PO’s en ontwikkelaars niet aangesproken op het feit dat ze documentatie moeten opleveren waar ze zelf helemaal geen behoefte aan hebben? Mijn ervaring is dat ze dat niet kunnen en ook niet willen. We moeten het ook niet aan ze vragen. Ontwikkelaars en testers moeten documenteren wat de code doet, zodat de code na vandaag ook nog begrijpelijk is. Als enterprise architect maakt dit soort documentatie me niet uit; ik kan het niet overzien. Wat ik wél belangrijk vind is dat een ontwikkelteam aan de betrokken architect(en) overdraagt wat er uiteindelijk gebouwd is. Dat gaat het best als de architect betrokken blijft. Mondeling, schetsjes, geen formele documenten.

Het is aan die architect om dat te borgen: proces en inhoud. Als we deze lijn volgen, is de angel uit ‘… comprehensive documentation’ (Manifesto) er in ieder geval al uit.

2. Project documentatie is niet bedoeld voor het lange termijn geheugen.

Of het nu een programmaplan, een project start architectuur, of foto’s van whiteboards zijn; dit zijn zaken die gemaakt worden om doel en uitvoering in lijn te brengen. Is het project eenmaal af, kan alles het archief in. Een projectarchief is meestal geen goede bron voor architecten. In de context van projecten hanteren we daarom andere kwaliteitseisen (fit for use) dan voor een enterprise repository (accuracy, consistency, etc.). Vanuit een enterprise architectuur perspectief wil ik gedurende en na een project een bijgewerkte repository, meer niet.

Deze richtlijn maakt het leven wat eenvoudiger.

3. Een repository onderhoudt de specificatie, en onthoudt de communicatie.

Een repository bevat de essentie van de architectuur. Het is niet nodig om heel veel viewpoints te tekenen. Je moet goede afspraken maken over wat minimaal nodig is om veelvoorkomende vragen te beantwoorden. De communicatie – uitleg, visualisaties, e.d. – is ook belangrijk, maar is vaak context specifiek. Mooie plaatjes onthouden is natuurlijk prima, maar onderhouden is iets anders. Als ik bijvoorbeeld per applicatie bijhoud welke applicaties of gebruikers de services afnemen, dan hoef ik niet hele landschapsplaten in te voeren en bij te houden. Die maak ik alleen als er behoefte aan is. Maar dat is dan relatief makkelijk, want wat ik wil tekenen hoef ik niet meer uit te zoeken; dat is beschikbaar in de repository.

Deze richtlijn maakt het implementeren van een repository een stuk haalbaarder.

4. Architectuur is de verbinding, niet de administraties.

Een CMDB (configuration management database) is een administratie. Een Product Diensten Catalogus is een administratie. Een Gegevenscatalogus is een administratie. Een Proceshuis is een administratie. Een administratie suggereert een houder en beheer. Architectuur gaat over de verbinding van die administraties. Bijvoorbeeld: welke applicaties ondersteunen welke processen? Welke gegevens worden door wie gebruikt?

Architecten willen vooral communiceren, verbinden en in het veld zijn. Voor het onderhouden van een repository heb je echter ook architectuurkennis nodig. Dat vraagt om discipline bij het hele architecten team, of om een dedicated ‘back-office architect’. Beide opties hebben zo hun uitdagingen, maar je moet het wel organiseren.

Deze richtlijn maakt duidelijk dat het hebben van een duurzaam onderhoudbaar geheugen vraagt om een bredere besturing van de informatiehuishouding. Dat vak heet Informatiemanagement.

5. Iemand is verantwoordelijk voor het corporate geheugen.

Een repository is niet iets dat vanzelf ontstaat. Vele organisaties hebben één of meerdere pogingen ondernomen. Wat nodig is dat er iemand van is. Ik stel me voor dat die persoon voldoende invloed heeft om er duurzaam budget voor vrij te maken. Iemand die voldoende visie heeft om te begrijpen dat dit een infrastructuur component is met een geweldig positieve business case. En bovendien iemand die in staat is om de architectuurfunctie zó te organiseren dat de repository actueel blijft. Dat kan overigens op meerdere manieren.

Deze richtlijn zorgt ervoor dat de architectuurfunctie effectief kan blijven bijdragen aan de ontwikkelinspanningen van de organisatie.

Deze richtlijnen kunnen alle bovenstaande redenen tenietdoen om geen documentatie te willen. Wat dan overblijft zijn redenen om het wél te doen, óf de constatering dat we te maken hebben met bestuurlijk onvermogen. Wat zal het zijn?

Serge Bouwens is een ervaren management consultant, enterprise architect en coach. Als consultant begeleidt hij organisaties bij de inrichting van de IT-functie. Als lead architect opereert hij vaak als meewerkend voorman bij het opstellen van een breed spectrum aan architecturen. Zijn stijl is pragmatisch en gericht op het slaan van bruggen tussen strategie en uitvoering.

Heeft u een vraag?

Neem contact op