scrummaster.nl

Documentatie is een belangrijk onderdeel van een software project. Requirements dienen opgeschreven te worden en architectuur en design opgeslagen in UML documenten. Allemaal met de goedbedoelde gedachte dat het in een later stadium gaat helpen voor iemand anders.

Een snelle test om te kijken hoe moeilijk, of hoe makkelijk, het is om nauwkeurig een verhaaltje te lezen. We beschrijven de ochtend van Tom:

Om acht uur gaat Toms wekker af. Om kwart over acht gaat hij naar de keuken en zet een grote pot thee. Rond een uur of half negen komen zijn vrouw en kinderen uit bed en gaan ze ontbijten. Om negen uur kust Tom zijn vrouw en kinderen gedag en rijdt hij naar zijn werk.

Gelezen? Beantwoord de vragen, zonder het verhaal opnieuw te lezen met ja, nee, of ik weet het niet. Dat laatste kan natuurlijk gebeuren als je het te snel leest.

Stond Tom om acht uur op? Ging hij om kwart over acht naar beneden naar de keuken om een grote pot thee te zetten? Heeft hij samen met zijn vrouw en kinderen rond half negen thee gedronken? Heeft hij twee kinderen? Reed hij met zijn auto naar zijn werk?

Bron: Psychologie Magazine mei 2011

Dit is een eenvoudig verhaaltje met niet al te moeilijke vragen. Als je echter een van de vragen bevestigend of ontkennend hebt beantwoord dan moet je het verhaal nog eens lezen. Voor elke vraag kan slechts gezegd worden dat het niet bekend is.

Hoe we het beantwoorden hangt af van onze eigen situatie en gewoontes. We vullen dus in naar dat zelf gewend zijn om te doen. Sta je gelijk op als je wekker gegaan is dan heb je de neiging om aan te geven dat Tom inderdaad om acht uur uit bed ging. Ben je gewend om nog even in bed te leggen dan heb je wellicht aangenomen dat Tom om kwart over acht in zijn pyjama naar beneden ging om de thee te gaan zetten.

Je hersenen doen dat niet voor niets. Ze moeten uit de continue stroom van de je omringende informatie zo snel mogelijk de kern weten te extraheren zodat je er op kan reageren. Indelen in voor jou bekende patronen helpen de hersenen om dat efficiënt te doen.

Hetzelfde fenomeen doet zich ook voor bij requirements documenten of design modellen. Voor de schrijver van het document is het duidelijk wat er geschreven staat, is het klip en klaar wat er bedoeld wordt. Voor de lezer is het net zo duidelijk, maar wel op zijn eigen manier.

Heb je veel achtergrond in enterprise projecten dan zal je automatisch de patronen toepassen die daar gebruikelijk zijn. Je zal ze als het ware zelf invullen in de UML diagrammen die voor je liggen. Groot zal de verrassing zijn als niet zo gedaan wordt als je dacht. De auteur kijkt je verbaast aan, je had het toch kunnen lezen?

Waar je bij UML diagrammen nog potentieel het voordeel hebt dat het minder ambigu zou moeten zijn, bij geschreven documenten is het nog lastiger. Menig document wat een project beschrijft en menig document waarin de requirements staan worden door de ontvanger gelezen om zijn manier, met zijn gedachtegang.

Bij de mogelijke antwoorden heb ik aangegeven dat je het ook zou kunnen beantwoorden met ‘ik weet het niet’, naar nu blijkt het juiste antwoord. Ik heb je echter proberen te beïnvloeden dat niet te doen door te stellen dat dat zou betekenen dat je waarschijnlijk de tekst te snel gelezen hebt, en dat is een beetje dom.

De angst om een beetje dom gevonden te worden speelt ook parten bij het lezen van documenten. Niemand wil dom gevonden worden en het is makkelijker om kleine vragen niet te stellen. Intelligente mensen begrijpen het namelijk wél.

Hieruit volgt dat dergelijke documenten slecht dienst doen als contract. Je kan als schrijver nou eenmaal niet bewust zijn van de onbewuste aannames van je potentiële lezers. Zelfs als je een review sessie organiseert weet je nog niet zeker of iedereen het invult zoals jij dat hebt gedaan, want ook jouw aannames zijn onbewust gemaakt.

Wees je bij elk geschreven document wat vast probeert te leggen wat en wat je gaat maken ervan bewust van de beperkte waarde ervan. Probeer het niet te compenseren door nóg meer te gaan schrijven. Eerder minder, je lezer gaat toch invullen.

Het Agile adagium “working software over comprehensive documentation” is niet zomaar een advies geboren uit frustratie of vanuit een Lean gedachte dat tussenproducten vermeden dienen te worden. Het is een gedegen advies, gesteund door de psychologie.