Home Innovatie & Strategie De waarde van software documentatie

De waarde van software documentatie

372

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.

  1. Beschrijf een stoel zodanig dat iemand anders op basis van jouw beschrijving een goede tekening van die stoel kan maken.
  2. 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

1 REACTIE

  1. Leuk artikel en redelijk mee eens. Documentatie wordt zelden gelezen en is zelden up-to-date. Vaak is het een requirement van een project en ontkom je er niet aan.

    Ik schrijf altijd een grapje er tussendoor “mail mij en ontvang taart!”, heb dit nog nooit hoeven te tracteren…

    Het niet documenteren in de code is echter een “technology debt”. Een schuld die je opbouwt en hoger wordt naarmate tijd verstrijkt en overigen complexiteit toeneemt.

LAAT EEN REACTIE ACHTER

Vul alstublieft uw commentaar in!
Vul hier uw naam in