Schrijf en teken

Nog steeds zijn er mensen die denken dat je de werkelijkheid in documenten en schema's kan vatten. Je schrijft de requirements van een nieuwe feature neer. De ontwikkelaars lezen die en, tadàà, een paar dagen later hebben ze gebouwd wat jij in je hoofd had.

Akkoord, documenten en schema's zijn handige en onontbeerlijke hulpmiddelen voor communicatie. Maar één van de moelijkste uitdagingen in geschreven documentatie - vraag het aan eender welke professionele schrijver – is te weten voor wie je schrijft. Wat is zijn/haar achtergrond? Wat weet ie al? Wat weet ie nog niet? Hoe goed kent ie je jargon? Hoe goed kent ie het vakgebied?

Het zijn mensen

Heb je je ooit afgevraagd bij het maken van een issue-ticket of een analyse "Welke ontwikkelaar zal dit uitvoeren? Als het Jef is, is het belangrijk dat ik erbij schrijf dat die knop groot genoeg moet zijn. Lisa weet dat echter al; haar moet ik er vooral op wijzen dat die knop best wat kleur mag hebben." Dàt is wat ik bedoel: je wil je communicatie afstemmen op je doelpubliek.

Documentatie schrijven die door iéder van je lezers begrepen wordt op dezelfde manier als jij het bedoelt, kost heel veel tijd en energie. Een kleine misrekening in het inschatten van je lezer kan bovendien al die tijd en energie verloren doen gaan.

Bij software is het probleem nog een beetje groter. Er zijn zoveel zaken waar je rekening mee moet houden dat het heel onwaarschijnlijk is dat je aan àlles hebt gedacht. Ongetwijfeld is er wel iets aan je aandacht ontsnapt, en heb je dat niet opgeschreven.

Is dat zo?

Hoe weet ik dat? Omdat ik regelmatig techbedrijven mag helpen om hun ontwikkelingsteam productiever en efficiënter te maken. Daarbij praat ik met alle leden van het ontwikkelingsteam. Eén van de meest gehoorde verzuchtingen die ik van developers hoor, is "De requirements zijn niet volledig genoeg. Ik moet heel veel zelf beslissen, en dan krijg ik achteraf het verwijt dat ik verkeerd beslist heb."

De meest gehoorde verzuchting van mensen die een bug rapporteren of een feature aanvragen daarentegen? "De developers verwachten dat ik een heel formulier invul met allemaal zaken waar ik niets van weet, en dan nog zijn ze niet tevreden. Kunnen ze nu zelf niet eens nadenken?"

Er zijn nog andere redenen waarom je niet alles in documentatie kan vatten. Andere en slimmere mensen dan ik hebben daar al uitvoerig over geschreven, zij het in een ietwat lastiger taalregister. Een voorbeeld is dit artikel van Naur .

Prààt

Om een goede communicatie in je productorganisatie te krijgen is het belangrijk om naast de geschreven documentatie ook een gesproken/face-to-face communicatie op te zetten. Geef je developers de kans om je vragen te stellen. Dat geeft jou de gelegenheid om te leren hoe zij jouw documentatie zien, en waar er nog gaten zitten in je manier van documenteren. En dat geeft de ontwikkelaars de gelegenheid om goed te begrijpen wat jij precies verlangt dat ze bouwen.