Code die nergens uitgelegd wordt, is een geheim dat alleen de maker kent. Zolang die maker beschikbaar is, valt dat mee. Maar mensen vertrekken, vergeten na een jaar hoe iets in elkaar zat, of zijn soms helemaal niet meer te bereiken. Op dat moment bepaalt documentatie of een ander verder kan, of dat je opnieuw moet beginnen.
Wat goede documentatie inhoudt
Het gaat niet om dikke handboeken die niemand leest. Goede documentatie legt de keuzes uit die niet uit de code zelf blijken: waarom iets zo is opgezet, hoe je het installeert en opstart, waar de gevoelige plekken zitten en wat je beter niet aanraakt. Het is de begeleidende brief bij wat je hebt laten bouwen, zodat een ander snel zijn weg vindt.
Wat het je oplevert
- Een andere ontwikkelaar kan moeiteloos verder waar de vorige stopte.
- Je zit nooit vast aan een enkele persoon of een enkel bureau.
- Onderhoud en uitbreiding gaan sneller en daarmee goedkoper.
- Kennis raakt niet verloren als iemand vertrekt of ziek wordt.
// documentatie is de brief die je aan je toekomstige zelf schrijft, of aan wie er na jou komt.
Zie het niet als extra werk achteraf, maar als onderdeel van het bouwen zelf. Wie tijdens het maken meteen vastlegt waarom hij iets zo doet, heeft er later nauwelijks omkijken naar. Het kost een fractie van de tijd die je anders kwijt bent met reconstrueren.
De code die zichzelf uitlegt
De beste documentatie zit deels in de code zelf: heldere namen, logische opbouw en een nette structuur maken dat veel uitleg overbodig wordt. Losse documentatie vult dan alleen aan wat de code niet kan vertellen. Zo blijft de uitleg ook actueel, want code die zichzelf uitlegt raakt niet verouderd zoals een los document dat wel kan.
Onderdeel van eigenaarschap
Eigenaar zijn van je website betekent niet alleen de code bezitten, maar ook kunnen begrijpen wat je bezit. Daarom hoort nette documentatie wat mij betreft bij de oplevering. Zo houd je de vrijheid om te kiezen met wie je verder werkt.
Houd documentatie ten slotte dicht bij de code en werk hem bij zodra er iets verandert. Een handleiding die ergens los rondzwerft en niemand meer aanraakt, raakt snel verouderd en wordt dan eerder misleidend dan behulpzaam. Actueel en vindbaar is belangrijker dan uitgebreid.
Wil je een project dat overdraagbaar is? Bespreek je project.
Verder lezen: Onderhoudbare code · Eigenaar van je site