Documentatie

Vroeger op het mainframe hadden we uitgebreide documentatie tools met ontwerpers die hun best deden om dat zo compleet mogelijk te laten zijn. Mijn eigen DocTool / MyProjects is daarop geïnspireerd (om te laten zien hoe ik zo'n tool zou maken). Wat Agile zegt over documenteren leek voor mijn gevoel misgeïnterpreteerd te worden om dat maar niet meer te doen want ontwerpen voordat je gaat bouwen werd denk ik maar vervelend en saai gevonden en documenteren achteraf schoot er al helemaal vaak bij in.

Op mijn werk keek ik uiteindelijk zelden in het ontwerp omdat ik in de code kon lezen hoe het echt werkte en zeker na de introductie van Agile kreeg ik sterke wantrouwens over de up-to-date- en betrouwbaarheid van datgene wat er was (en omdat er in latere jaren veel met externen gewerkt werd was er ook heel veel gewoon niet).

Later werkte ik vaak samen met een ontwerper om te zorgen dat wat we bouwden ook op de juiste manier in specifikaties terecht kwam, gelukkig hadden we er een in het team die het ook belangrijk vond om ergens terug te kunnen vinden hoe iets verondersteld wordt te werken (hoe weet je anders dat het doet wat de bedoeling is?).

En als er niet ijverig gedocumenteerd werd aan de spullen die ik gebruik om mijn eigen spullen te maken zou ik veel meer moeite hebben om te weten hoe ik ze moest gebruiken.

Bedenken wat je moet / kunt documenteren is MOEILIJK. Het valt denk ik uiteen in twee categorieën: - wat de software doet / zou moeten doen. Hieronder valt volgens mij ook wat je zou kunnen noemen de gebruikershandleiding - hoe de software is opgezet. Dit kan helpen bij het oplossen van problemen

Bij het bedenken / opschrijven van het bovenstaande valt het me op dat dit overeenkomt met wat we vroeger noemden Functionele en Technische documentatie.

Ik heb het gevoel dat Agile of zoals het geïnterpreteerd wordt vooral de eerste categorie belangrijk vindt en de tweede meer plaatst bij de vluchtige project documentatie wat wel een beetje klopt, technische oplossingen kunnen over tijd veranderen en zijn altijd aan de hand van de code te achterhalen. Maar ontwerpbeslissingen lijken me toch wel handig om vast te houden, ze beschrijven ten slotte ook een beetje het waarom en niet zozeer het hoe.

In de documentatie die ik zelf schrijf en die elders op deze site te vinden is komt vooral de eerste categorie terecht, met denk ik het accent op het gebruikershandleiding aspect. Dat is ook het meest publieke gedeelte, zeker omdat ik de enige ben die belang heeft bij de tweede categorie. Die hou ik momenteel meer voor mezelf en bewaar ik op dezelfde plek als de code zelf. En ik moet eerlijk bekennen dat ik het beschrijven af en toe meer doe om beter te snappen wat ik ook weer gedaan heb, dan om het de volgende keer over te lezen in plaats van het nog eens over te doen.