Image via Wikipedia
De schrijvers van het Agile Manifesto vinden working software belangrijker dan comprehensive documentation. Zo direct gesteld zal iedereen het daar wel mee eens zijn. Maar de vraag blijft wel wat dan de waarde is van documentatie. Moeten we helemaal stoppen met het schrijven van design documentatie? Het laatste zinnetje van het Manifesto geeft al aan dat dit niet het geval kan zijn: there is value in the items on the right, er zit dus waarde in het schrijven van documentatie, we value the items on the left more, maar we moeten het niet overdrijven.
Vaak wordt gesteld dat we documentatie schrijven voor beheer. Als het project klaar is en later bugs moeten worden opgelost of aanpassingen worden gedaan, dan is documentatie noodzakelijk. Echter, ik vraag vaak aan beheerders hoe dat dan werkt in de praktijk. “Waar kijk je naar als je een bug moet oplossen, naar de documentatie of naar de source code?” Bijna zonder uitzondering krijg ik dan source code als antwoord. Blijkbaar lukt het meestal ook wel zonder documentatie. Eén van de redenen die daarvoor genoemd wordt is dat documentatie vaak niet helemaal up-to-date is. Het lastige daarbij is dat één klein foutje in de documentatie de gehele documentatie onbetrouwbaar maakt. Dan is de source code toch de enige echt betrouwbare bron. Wat wel vaak als nuttig genoemd wordt is een globaal structuurplaatje: “Welke modules zijn er en hoe hangen ze samen?”.
Alistair Cockburn verwijst in zijn excellente boek Agile Software Development – The Cooperative Game naar Ludwig Wittgenstein. Wittgenstein laat mensen kiezen tussen twee opties om de (on)mogelijkheid van documentatie aan te tonen.
- Beschrijf een stoel zodanig dat iemand anders op basis van jouw beschrijving een goede tekening van die stoel kan maken.
- Beschrijf het geluid van een klarinet zodanig dat iemand anders kan raden welk instrument je beschreven hebt.
Het antwoord ligt voor de hand, optie 2 is onmogelijk. Cockburn stelt nu dat veel software documentatie lijkt op het beschrijven van het geluid van een klarinet. Jammer genoeg mist het de essentie. Als je op basis van documentatie alleen moet bepalen hoe je een uitbreiding op een systeem moet inpassen in het bestaande systeem maak je vaak niet de optimale keuze. Even kort spreken met het team dat het oude systeem ontwikkelde levert veel sneller een veel betere keuze op. Zo geldt ook we value individuals and interactions over comprehensive documentation.
Andre Heijstek's Blog 
De oplossing verondersteld wel dat er gelegenheid is om met het team te kunnen spreken dat het orginele product ontwikkelde. Hoewel beperkt zie ik in de praktijk nog wel eens dat er een aanpassing moet komen op een product waarvan degenen die het gemaakt hebben allang weg zijn.
Hoi Benjamin, daar heb je natuurlijk helemaal gelijk in. Als het originele team er niet meer is kan je er ook niet meer me praten. Dat pleit in de eerste plaats voor een lange termijn visie. Elke keer een blik detacheerders opentrekken om een product te ontwikkelen is op korte termijn wel handig, maar op lange termijn niet.
Als het originele team er niet meer is, zul je moeten roeien met de riemen die je hebt. Hopelijk is de source code goed gestructureerd en van nuttig commentaar voorzien. Daarnaast is dan, zoals ik schreef, een structuurplaatje erg handig. En goede gebruikersdocumentatie is ook voor een nieuw ontwikkelteam erg nuttig.
Wat is jouw ervaring in de praktijk?
Waar het volgens mij beter kan, is het compact beschrijven van systemen, “leave out the obvious, and describe what is not explicit”.
Ik ben momenteel aan het experimenteren met een nieuwe wijze van documenteren die momenteel door de ontwikkelaars goed wordt ontvangen, en door de klant (zij het schoorvoetend) ook.
Hallo Koen, ik ben heel benieuwd hoe je dat aanpakt. Kan je een tipje van de sluier oplichten?
Hoi André,
ik zou hier een tipje van de sluier op kunnen lichten. Het is alleen echt nog een heel prille werkwijze, waarbij het pilot project nog niet is afgerond. Vandaar dat ik wat terughoudend ben, maar denk in een combinatie van business rules en een grafische representatie waarin deze rules gebruikt worden.