dinsdag 17 mei 2011

Klassiek documenteren lijkt achterhaald

Een project loopt ten einde en nu moet ik documentatie opleveren en dat valt me erg zwaar. Mijn project bestond uit allemaal dingen, maar ook uit het opleveren van tools ter verbetering van operationele en management informatie. En van die tools moet ik nu documentatie schrijven.

Dit klinkt heel logisch, is heel logisch en naast dat het me heel veel moeite en discipline kost, heb ik ook het gevoel dat ik het niet goed doe. Daarbij zet ik vraagtekens bij de noodzaak van documentatie in deze hoedanigheid. Dit klinkt misschien als onhandig om dit zo op te schrijven op het “wereld wijde web“ en als er geen diepere gedachte achter zou zitten klopt dit inderdaad.

Allereerst zijn er natuurlijk de clich├ęs. Ik heb er geen zin in en niemand leest het. De reden waarom ik het meestal ook uit mijzelf doe is dat het meteen een manier van indekken is. Bij problemen kun je altijd terugvallen op de documentatie. Heb je geen documentatie ben je altijd de klos in een discussie. Dat niemand het leest lijkt ook wel redelijk bewezen. Ik beloof lezers van mijn documentatie altijd gebak als ze mij mailen en vooralsnog zijn banketbakkers weinig met mij opgeschoten. Overigens gaat ontwikkeling na oplevering altijd door en loopt documentatie per definitie achter, maar ook daar schrijf ik dit stuk niet voor op.

Hoe zou documentatie eruit moeten zien? Die definitie kan ik wel geven. Als ik bij een project instroom is het heerlijk als er documentatie aanwezig is met details over het domein van het project, de geschiedenis en een beschrijving van de onderliggende behoefte waarom het project gestart is. Ook en nog een verklarende woordenlijst zodat ik dingen begrijp als ik ze tegenkom.

Bevat mijn documentatie deze informatie. Nee. Documentatie is een verplichting die je inwilligt en dat doe je door een beschrijving te geven van alles wat er is gemaakt, maar juiste deze informatie is triviaal. 90% van de tabelgegevens spreken voor zich, het zijn juist de angels, uitzonderingen, oplossingsrichtingen bij problemen die je wilt lezen als er geen hulp beschikbaar is. Ik voorzie code altijd al van noodzakelijk commentaar, een logische flow en in de tabel probeer ik elke veld altijd een beschrijving mee te geven, documentatie voegt daar weinig aan toe.

Is de ontwikkelaar ook wel de juiste persoon om te documenteren? Hij zal het in de regel zonder inspiratie doen en als sluitpost en verplichting. Daarnaast kun je een goede ontwikkelaar zijn, maar wat is je kunde om in duidelijke taal te schrijven? Hoeveel ervaring als schrijver heb je nu eigenlijk? En hoe kom je tot de crux en verwoord je de inzichten die je had tijdens het oplossen van angels en problemen tijdens de ontwikkeling? Het is best lastig om je probleem te beschrijven als je dit al opgelost hebt. In retrospectief lijkt alles een koekje.

Het laten schrijven van documentatie door de ontwikkelaar is ook een soort gemakzucht. Het kan de opdrachtgever vaak niet veel schelen en zal er in de regel ook zelf weinig moeite voor doen, maar juist het vastleggen en overbrengen van kennis (wat je beoogt met documentatie) ontstaat uit dialoog. De leerling die de mentor bevraagd. Eigenlijk zou documentatie moeten ontstaan uit de interviews die de nieuwe ontwikkelaar of beheerder heeft met de huidige ontwikkelaar. Bij het inwerken stel je veel vragen en heeft de nieuwe verantwoordelijke er baat bij kennis over het project op te doen.

Mijn inzicht is dus dat documenteren een het eind van het project niet succesvol lijkt en een verspilling. Documentatie moet ontstaan als product uit een overdracht. Pas dan borg je ook dat het gewenste op papier komt en dat er iemand is die echt gemotiveerd is de kennis op te doen.

Ik wil dit inzicht in de praktijk gaan brengen, ik zit er momenteel namelijk middenin. Soms lijken dingen logisch, maar is het in de praktijk veel beter om het anders te doen en minder voor de hand liggend. Als ik hierover ervaring op doe, zal ik het direct documenteren…