MS-Word is geen plek voor documentatie. Een tekstbestand wel.

Mijn dochter krijgt een MS-Word-sjabloon toegestuurd als basis voor haar bachelor-scriptie.

Dat verbaasde me, en eerlijk gezegd vind ik het onbegrijpelijk. Tijdens mijn eigen IT-opleiding werkten we al met LaTeX: geen MS-Word, geen muis, geen even snel iets opmaken.

Serieuze documentatie hoort niet in MS-Word. Die hoort in een tekstbestand.

Een academische erfenis: inhoud boven layout

LaTeX is populair in de wetenschappelijke wereld, en dat is geen toeval. Onderzoekers schrijven artikelen die later worden gebundeld tot conferentieboeken en journals met een uniforme uitstraling. De afspraak is simpel: jij levert structuur en inhoud, de uitgever zorgt voor de opmaak.

Die scheiding zit nog steeds in elke moderne opmaaktaal. Of het nu LaTeX is, AsciiDoc, of het inmiddels alomtegenwoordige Markdown: jij beschrijft waar iets over gaat, niet hoe het eruit moet zien. Een paragraaf is een paragraaf, een kop is een kop, een lijst is een lijst. De opmaak komt later, en wisselt van publicatie tot publicatie.

Tekstbestanden zijn tijdloos

Een ander argument is praktisch. Een platte tekst kun je over twintig jaar nog openen. Het kost je geen licentie, geen specifieke versie van een editor, geen cloudaccount. Dat klinkt klein, maar bij documentatie die jaren of decennia mee moet, is het alles.

Versiebeheer (Git) en platte tekst zijn voor elkaar gemaakt: elke wijziging is per regel zichtbaar, twee mensen kunnen tegelijk schrijven en hun werk laten samenvoegen, en oude versies opzoeken is een kwestie van één commando. Probeer dat eens met een MS-Word-document van vijftig pagina’s.

Eén bron, vele publicaties

Een opmaaktaal kan dezelfde bron in veel vormen publiceren. De inhoud van deze website is geschreven in AsciiDoc; de pagina die je nu leest komt uit een plat tekstbestand, zonder opmaak. De technische documentatie van ons framework en ERP-systeem komt rechtstreeks uit de Java-projecten waarin we de software bouwen, met hetzelfde versiebeheer, in hetzelfde formaat.

Dezelfde tekst kan een PDF worden, een handout, een interne wiki, een onderdeel van een productpagina. Eén bron, veel doelen. Dat is geen aardigheidje; het is precies wat documentatie houdbaar maakt.

Blik onder de motorkap

Onderstaand het begin van deze blog-post, zoals ik die heb geschreven in platte tekst (AsciiDoc).

[quote.pullquote]
Mijn dochter krijgt een MS-Word-sjabloon toegestuurd als basis voor haar bachelor-scriptie.

Dat verbaasde me, en eerlijk gezegd vind ik het onbegrijpelijk. Tijdens
mijn eigen IT-opleiding werkten we al met https://en.wikipedia.org/wiki/LaTeX[LaTeX]:
geen https://en.wikipedia.org/wiki/Microsoft_Word[MS-Word], geen muis, geen _even snel iets opmaken_.

Serieuze documentatie hoort niet in MS-Word. Die hoort in een tekstbestand.

== Een academische erfenis: inhoud boven layout

LaTeX is populair in de wetenschappelijke wereld, en dat is geen toeval.

Twee = maken een kop, een lege regel begint een nieuwe paragraaf. De quote-tag geeft alleen aan dat het een quote betreft, niet hoe deze moet worden weergegeven. De rest, lettertype, kleur, marges, regelt de site bij het bouwen.

Een persoonlijke teleurstelling

Tien jaar geleden schreef ik voor een groot Java-project uitgebreide technische documentatie in AsciiDoc, naast de code, onder hetzelfde versiebeheer. Bij elke release liep de documentatie automatisch mee.

Een jaar later kwam ik terug bij die klant. De AsciiDoc was weg, ontwikkelaars hadden alles overgezet naar één MS-Word-document van een paar honderd pagina’s, geheel los van de code. Ik heb op mijn tong moeten bijten. Uiteindelijk is de klant koning; wij kunnen niet meer doen dan adviseren.

Maar het tij keert

In software is Markdown inmiddels gewoon de standaard en met de komst van AI wordt het bekender bij het brede publiek. README’s, technische blogs, AI-skills, het zit allemaal in tekstbestanden. Tien jaar geleden moest ik dit nog uitleggen; vandaag hoeft dat zelden.

Documentatie gaat niet over hoe het eruit ziet. Het gaat over wat er staat, en of het over een paar jaar nog leesbaar en juist is.

In de software- en AI-wereld is dat besef doorgedrongen. Op de universiteit blijkbaar nog niet, getuige dat MS-Word-sjabloon van mijn dochter.