Skip to content

Documenteren is leuk

30 juli 2016

De meeste IT-ers hebben een hekel aan documenteren, maar ik vind het juist leuk. Het opzetten van documentatie is het bouwen van een systeem, het is vergelijkbaar met programmeren. Je kiest uit wat je wel en niet opschrijft en je zoekt de manier uit waarop je dat het beste kunt presenteren, in welke volgorde en met welke verwijzingen en dwarsverbanden. Om dat op te zetten moet je analyseren, systematisch denken en zorgvuldig zijn, want alles moet kloppen. Het is het leukst wanneer je niet schrijft voor een resultaat in de vorm van een papieren document, maar in een of andere op HTML gebaseerde vorm (bijvoorbeeld executable HTML). Dan lijkt documentatie nog het meest op software.

 

Waarom documenteren we eigenlijk? Het antwoord is eenvoudig, dat doe je met de verwachting dat jezelf of iemand anders daar (later) wat aan heeft. Het is het makkelijkste als je alleen voor jezelf documenteert. Dan weet je wat je wilt onthouden en de feedback als je het niet goed gedaan hebt, is het duidelijkst als je jezelf verwijten maakt. Misschien ontdek je dan dat je alles moet opschrijven wat je van te voren niet wist, wat je hebt moeten uitzoeken, omdat je anders later denkt “Hoe zat het ook al weer” en je het nog een keer moet uitzoeken.

Grote lijnen

Wat moet je documenteren en wat niet? Wat zal je toekomstige collega willen opzoeken? In de eerste plaats de grote lijnen, zeg maar de dingen die je mondeling aan een nieuwe collega zou vertellen, gecompleteerd met een of enkele schema’s die een overzicht van de structuur weergeven. Wat vaak ook handig is, is om van functies in één zin te beschrijven wat die doen. Dus weer een grote lijn. Dat schrijf je dan vooral in de programmacode zelf, want anders wordt het toch niet gelezen.
Het documenteren van details is soms nuttig, maar vaak ook niet omdat die zonder documentatie ook gevonden kunnen worden. Het heeft bijvoorbeeld geen zin om van een tabel van alle velden de eigenschappen te documenteren. Als iemand het weten wil, kijkt hij toch in de database zelf. Van de documentatie moet je maar afwachten of die nog up-to-date is.

Zoekwoorden

Je moet die dingen opschrijven die iemand die met je produkt werkt, wil weten. Voor wie schrijf je en wat doet de lezer voor werk? Is hij gebruiker van het produkt of een technicus die het produkt onderhoudt? Voor beide soorten lezers geldt dat ze de documentatie liever niet lezen. Niemand leest de handleiding zolang het ook zonder kan. Mensen beginnen gewoon wat te proberen en pas als ze vastlopen, gaan ze de handleiding erbij pakken. Volgens velen is dat een menselijk tekort, maar ik zie dat anders. Mensen leren graag door te doen, door te ontdekken, dat doen ze liever dan dat ze een saaie tekst lezen. Want al ben je nog zo’n vlotte schrijver, documentatie blijft saai. Wat wil iemand over dit produkt opzoeken? Op welke termen zal hij zoeken?

Waarom

Wat volgens mij ook nuttig kan zijn, is om te documenteren welke beslissingen er zijn genomen. “Wat” de software doet is namelijk altijd wel te achterhalen, maar het “waarom” niet. Houdt bij waarom je iets op een bepaalde manier doet. Waarom gebruik je het ene type in plaats van het andere? Waarom gebruik je een bepaalde tool in plaats van een andere? Wellicht zal iemand die voldoende kennis heeft, de beslissing ook zonder toelichting wel begrijpen, maar iemand met wat minder kennis niet. Dus hier geldt zeker: als je het zelf niet wist, is het goed om het op te schrijven.

Spaarzaam

Schrijf vooral niet teveel. De meeste IT-ers hebben een hekel aan documenteren, maar als ze het doen dan schrijven ze teveel zaken op die nooit meer gelezen worden. Het moet wel leuk blijven! Sommige dingen kunnen gewoon beter al doende geleerd worden. Documenteren moet ervoor zorgen dat het wiel niet telkens opnieuw uitgevonden moet worden. Maar dat geldt voor het documenteren zelf ook! Daar wordt het wiel ook telkens opnieuw uitgevonden.

Advertenties

From → Wetenschap

Geef een reactie

Geef een reactie

Vul je gegevens in of klik op een icoon om in te loggen.

WordPress.com logo

Je reageert onder je WordPress.com account. Log uit / Bijwerken )

Twitter-afbeelding

Je reageert onder je Twitter account. Log uit / Bijwerken )

Facebook foto

Je reageert onder je Facebook account. Log uit / Bijwerken )

Google+ photo

Je reageert onder je Google+ account. Log uit / Bijwerken )

Verbinden met %s

%d bloggers liken dit: