De ongemakkelijke kloof tussen ontwikkelaars en officiële documentatie

“Is het dat ik de documentatie niet kan begrijpen omdat ik niet bekwaam genoeg ben?” Ik heb dit al een hele tijd zo gedacht.

1. “Ik dacht dat alleen ik het niet begreep”

Frameworks, libraries, REST‑API’s, cloud‑services… Nu is bijna alles goed gedocumenteerd. Het probleem is… ik het simpelweg niet goed begrijp.

In het begin dacht ik zo:

“Ah… ik ben nog niet genoeg bekwaam. Als ik meer studeer, zal ik op een dag deze documentatie ook moeiteloos kunnen lezen…”

Dus ik lees hardop. Maar:

• Ik begrijp de principes niet
• Ik ben in de war over wat conceptueel is en waar de praktische voorbeelden beginnen
• Ik heb de inhoud gelezen, maar als ik code moet schrijven, weet ik niet waar te beginnen
• Waarom is de documentatie zo omvangrijk?

Ik denk nu dat ik een ontwikkelaar ben die niet meer als “beginner” wordt gezien. Toch hoor ik nog steeds die stem in mijn hoofd als ik een nieuwe library‑documentatie zie.

“Wow… hier gaan we weer.”

Ik weet nu dat het niet alleen een gebrek aan vaardigheid is.

2. Documentatie is meestal geschreven vanuit het perspectief van de maker

De grootste reden waarom documentatie moeilijk is, is dat de meeste officiële documentatie is gebaseerd op het mindschema van de maker.

• Die persoon weet al
• de interne structuur
• waarom bepaalde keuzes zijn gemaakt
• welke beperkingen er zijn
• waar en hoe functies worden aangeroepen
• Daarom bevat de documentatie vaak:
• “Deze methode accepteert deze parameters”
• “Dit type wordt geretourneerd”
• “In dit geval wordt een uitzondering gegooid”
• “Met dit kun je dit doen”

Het probleem is dat wij niet de maker van het programma zijn.

Wat we meestal willen weten, zijn vragen als:

• “Waar moet ik beginnen?”
• “Welke deel van de documentatie moet ik raadplegen om dit probleem op te lossen?”
• “In welke situatie is deze optie echt nodig?”
• “Wanneer wordt deze code werkelijk aangeroepen?”

Maar de documentatie zegt:

“Deze optie voert de actie foo uit met de strategie bar om baz te realiseren.”

…en dan wil je gewoon een voorbeeld draaien.

3. “Mijn eigen documentatie is ook moeilijk voor anderen”

Het grappige is dat ik ook documentatie schrijf over de API’s of libraries die ik maak. Dan schrijf ik ook weer vanuit het perspectief van de maker.

• “Deze functie doet X…”
• “Deze endpoint accepteert Y…”
• “Dit JSON‑object wordt geretourneerd…”
• “Bij succes/failure is de respons zo…”

En ik denk:

“Is dit niet al vrij vriendelijk?”

Maar de reactie van mijn teamleden is meestal:

• “Kun je het eerst mondeling uitleggen?”
• “Er is een document, maar het is sneller om gewoon te vragen.”

Het grappigste is dat ik soms mijn eigen documentatie niet meer herken.

Een oude API opnieuw gebruiken en de oude documentatie openen:

“Hmm… is dit iets wat ik heb geschreven? Waarom heb ik het zo vreemd uitgelegd…?”

Ik besefte toen:

• Documenteren betekent niet automatisch dat het begrijpelijk is.
• Ik heb geen recht om de officiële documentatie te bekritiseren als ik het niet begrijp. 😅

4. Het is normaal dat officiële documentatie in het begin niet meteen duidelijk is

Elke project heeft een library of package die je constant gebruikt. Je houdt die documentatie vast in een tab en bekijkt hem terwijl je werkt.

Er is iets fascinerends:

• Bij het eerste lezen lijkt de tekst vaak onbegrijpelijk.
• Bij het einde van het project kun je terugkijken en begrijpen wat er werd bedoeld.

En ik denk vaak:

“Ik dacht dat dit hier stond, maar nu begrijp ik het…”

Waarom gebeurt dit?

• Om de inhoud te begrijpen, heb je ervaring en context nodig.
• Om die ervaring op te doen, moet je documentatie lezen en iets bouwen.

Je raakt dus in een cirkel: om de documentatie te begrijpen, moet je de documentatie begrijpen.

Daarom denk ik nu:

“Officiële documentatie is niet bedoeld om meteen te begrijpen. Je moet het meerdere keren doorlopen terwijl je aan projecten werkt.”

Het is dus normaal dat het in het begin niet duidelijk is.

5. Niet‑Engelstalige ontwikkelaars hebben een extra +2 in moeilijkheid

We hebben ook het handicap van niet‑Engelstalige ontwikkelaars.

• Ik kan de Engelse zinnen lezen.
• Technische termen zijn nu vrij bekend.
• Ik lees graag boeken en artikelen, dus ik voel me niet “tekort aan leesvaardigheid”.

Toch wordt het lezen van officiële documentatie vaak minder energiek.

Dit komt niet door gebrek aan vaardigheid, maar omdat:

• Engels vereist continu cognitieve belasting.
• Daarbij komen
• nieuwe concepten
• onbekende API‑ontwerpen
• abstracte voorbeeldcode
• allemaal tegelijk.

Ik speel dus een spel waarbij ik meer energie verbruik dan anderen om dezelfde informatie te begrijpen.

Daarom voel ik me vaak vermoeid en vind ik het moeilijker.

Wanneer ik denk: “Waarom is het zo moeilijk om officiële documentatie te lezen?” Kun je jezelf geruststellen met:

“Ik ben al bezig met een handicap, maar ik blijf hard werken.”

6. Toch… we hebben een paar overlevingsvaardigheden

Hier zijn een paar documentatie‑overlevingsstrategieën die ik heb geleerd.

6‑1. Laat de wens om alles van begin tot eind te lezen los

• Officiële documentatie is vaak een referentie + woordenboek.
• Het is niet een beginnersboek dat je van pagina 1 tot eind moet lezen.

Dus ik:

• Bekijk alleen de Getting Started / Quickstart / Tutorial secties.
• Gebruik de rest als
• zoekfunctie
• probleemoplossing

6‑2. Begrijp eerst met een voorbeeld, lees daarna de uitleg

• Schrijf een regel code.
• Laat een fout optreden.
• Zoek de foutmelding op en lees de documentatie opnieuw.

Dan verandert de tekst:

• Bij het eerste lezen:

  “Ik begrijp dit niet…”

• Na een paar pogingen:

  “Ah, dit is de fout die ik eerder had.”

Na een mislukte ervaring wordt de documentatie verhalend.

6‑3. “Schrijf het in je eigen taal”

Omdat de officiële documentatie in hun taal is, maak ik vaak aantekeningen:

• “Als je deze optie op true zet, is het eigenlijk XXX mode.”
• “Deze functie is een ‘fabriek’ die X maakt.”
• “Onthoud dit, diepgaand begrip later.”

Later, wanneer ik mijn eigen documentatie bekijk, vormt het een set met de officiële, waardoor het veel sterker wordt.

7. Het is niet jouw fout

Als je dit tot nu toe hebt gelezen, heb je waarschijnlijk ook eens een zucht uitgeblazen voor officiële documentatie.

• Zinnen die meerdere keren gelezen moeten worden
• Secties die je gisteren zag maar vandaag moet opzoeken
• Zinnen die pas duidelijk worden na het oplossen van een probleem

Onthoud:

• Je bent niet de enige.
• Veel goede ontwikkelaars worstelen ook.
• Zelfs mensen die de library dagelijks gebruiken zoeken vaak naar Stack Overflow of GitHub issues in plaats van de officiële documentatie.

Officiële documentatie is van nature moeilijk.

En dat is niet jouw fout.

We doen gewoon:

• Als het niet duidelijk is, lees opnieuw.
• Schrijf code.
• Als het nog steeds niet duidelijk is, ga terug naar de documentatie.
• En op een dag

  “Ah, dus dit is waarom de auteur dit schreef.”

Dit is een deel van het leven als ontwikkelaar.

Dus als je vandaag nog gefrustreerd bent, zeg het aan iemand:

“Je maakt geen fout. Je bent gewoon in de normale ontwikkelaarssnelheid.”

We blijven allemaal gefrustreerd, we hebben tientallen tabs open, we zoeken de pagina die we gisteren bekeken, maar projecten blijven draaien en we leren steeds meer code. 🙂