RTFM

Software-engineers en andere IT'ers hebben een gruwelijke hekel aan documenteren. Deels omdat beschrijven en uitleggen altijd na het werk komt waarvoor ze eigenlijk gekozen hebben. Ze gaan liever aan de slag met het volgende probleem. Deels omdat ze vinden dat de geïmplementeerde oplossing voor zich spreekt. En ten slotte omdat ze niet van de woorden zijn en documenteren dus relatief veel van hun tijd in beslag neemt.

Een bijkomend probleem is de doelgroep. Schrijf je als IT'er voor je collega's, die onderhoud moeten plegen en aanvullende code moeten schrijven? Of voor de gebruiker? En wie is die gebruiker dan? Is het een applicatie- of systeembeheerder, van wie je wel wat voorkennis mag verwachten? Hoeveel voorkennis dan? Of is het een eindgebruiker, die nog helemaal in de denkwijze van de software-engineer ingevoerd moet worden? Voor wie iedere overgeslagen, ongedocumenteerde stap tot frustratie leidt?

En heb je je toch met tegenzin in dit mijnenveld 'documenteren' laten jagen, dan krijg je te maken met softwareversies, met klanten die bepaalde opties niet hebben aangeschaft, met aansluitingsproblemen met software van andere leveranciers, met workarounds waar je niet trots op bent …

Anderzijds leest niemand voor zijn plezier documentatie bij software-oplossingen. Ook daarvoor zijn verschillende redenen. Een handleiding lezen is altijd saai: je weet wat je wilt en je vindt dat je intuïtie je naar het resultaat moet brengen dat je voor ogen hebt. Als dat niet lukt, ben je al een beetje gefrustreerd. Dan begin je met tegenzin te lezen en blijkt de tekst ook nog eens volkomen onbegrijpelijk – want in strijd met je intuïtie.

Geen wonder dat de doorsnee IT'er 'maar wat doet'. Dat is namelijk het antwoord dat ik kreeg toen ik rondvroeg na een aanvraag voor een training Schrijven van IT-documentatie. Geen enkele van mijn netwerkcontacten 'in de IT' kon mij uitleggen wat ten grondslag ligt aan hun documentatie. Ze gebruiken geen naslagwerken, geen schrijfwijzers, geen onderlinge afspraken, geen richtlijnen. Het mijnenveld is een woestijn die niet in kaart is gebracht.

Ik heb daar niet direct een oplossing voor. Maar ik denk graag met je mee als je goede documentatie op poten wilt zetten. Een poging daartoe heb ik onlangs gedaan bij SURFsara. In de voorbereiding daarop heb ik ook een aardig boek gevonden.

* RTFM is wat helpdeskmedewerkers onderling mompelen als jij ze je computerproblemen voorlegt: Read The Fucking Manual.