Documentatie genereren met AI: van code naar documentatie

Documentatie bijwerken schiet er bij de meeste ontwikkelaars al snel bij in. Het is belangrijk, maar concurreert met de tijd die naar de code zelf gaat. Vincent experimenteert daarom met een opzet waarin documentatie automatisch wordt gegenereerd vanuit de code die hij schrijft, met Claude Code en Obsidian. In dit artikel vertelt hij er meer over.

Tekst: Vincent van Middendorp

Klein zijstapje maar toch het noemen waard: We bevinden ons in een interessante overgangsperiode. Aan de ene kant de (web)developer die een deel van zijn taken (of inmiddels vrijwel alle) uitbesteedt aan een LLM + harness zoals Claude Code, en die elke stap expliciet laat uitvoeren en goedkeurt. Aan de andere kant de volgende fase, waarin agents autonoom aan de code sleutelen zonder dat een developer ze 'babysit'. Dat laatste wordt in de nabije toekomst steeds gebruikelijker. De inrichting die ik hieronder beschrijf is vooral gericht op het heden (de developer zit nog aan het stuur) maar een soortgelijke documentatie-output kun je ook in een volledig geautomatiseerd scenario integreren. Dat gezegd hebbende: terug naar Obsidian.

Het is eenvoudig om dagelijkse notities te handmatig te vullen en te groeperen in Obsidian. Om het meer te automatiseren experimenteer ik nu met deze indeling (ik claim niet dat dit een best practice is):

• Een vault met handmatig getypte notities (voornamelijk steekwoorden) per klant. Dit kan bijvoorbeeld input zijn vanuit meetings.
• Een vault voor automatisch gegenereerde, volledig leesbare documentatie per klant in twee vormen: gebruikersdocumentatie en technische documentatie.

Een 'vault' in Obsidian is eigenlijk gewoon een map op je filesystem met markdown (tekst) files. (Een Obsidian vault per klant in versiebeheer naast de applicatie-code zou een logische vervolgstap zijn).

Als ik in Claude Code aan een project werk vraagt deze nu aan het eind van een feature bouwen of een bugfix maken of er documentatie aangemaakt moet worden in de tweede vault. De klantnaam wordt automatisch afgeleid uit de map waarin Claude Code werkt. De nieuwe documentatie is gebaseerd op de geschreven code, de gemaakte keuzes en eventuele eerdere versiebeheer-historie. Daarnaast wordt gekeken of er input is uit vault 1 (handmatige notities) om bijvoorbeeld bepaalde implementatie keuzes beter te kunnen onderbouwen.

Output bij de gebruikersdocumentatie is bijvoorbeeld: " Velden X & Y zijn nieuw in het contentmanagementsysteem. Bij veld X moet verplicht een locatie gekozen worden en bij veld Y een persoon. Na publiceren vertaalt dat zich op de volgende manier naar de voorkant van de webapplicatie."

De technische documentatie legt uit welke API-koppelingen er zijn, welke caching-strategie wordt gebruikt, enzovoort.

Voorbeeld van "documentatie opslaan?" vraag tijdens Claude Code-sessie.

Bij latere wijzigingen in dezelfde feature weet Claude de documentatie te vinden en vraagt het of deze bijgewerkt moet worden. Zo blijft de documentatie ook daadwerkelijk relevant.

Al het bovenstaande regelen in Claude Code is eenvoudig. Er is een custom SKILL (grotendeels door Claude Code zelf geschreven), een HOOK (reminder om te vragen of documentatie gegenereerd moet worden) en een paragraaf in het algemene CLAUDE.md-configuratiebestand met de paden naar de Obsidian-vaults en een verwijzing naar de SKILL. In de SKILL staat ook beschreven wat er absoluut niet in documentatie terecht mag komen: persoonsgegevens, secrets (wachtwoorden, API-keys, etc.) bijvoorbeeld. Daarnaast staat erin wat de logica is voor naamgeving van de notities, zoals het user story-nummer in titel zetten. Bij interesse kan ik de skill en configuratie delen maar met Claude Code zou je een heel eind moeten komen.

Nu kan ik mij voorstellen dat je denkt: oké, dit levert een bak met tekst op. maar is het ook bruikbaar? Daar is een kort antwoord voldoende: ja. Het levert overzichtelijke documentatie specifiek gericht op dat ene nieuwe component dat is toegevoegd.

Natuurlijk blijft een menselijke review van groot belang om te zien of er geen hallucinaties in zijn geslopen of dat er iets anders aan schort. Niet voor elke wijziging is documentatie nodig en ik heb graag controle. Daarom heb ik het aanmaken ingesteld als vraag en niet als volledig automatisch proces (zelf tussendoor de skill aanroepen is ook altijd een optie). Verder is het zaak om de gebruikersdocumentatie uit vault 2 ook daadwerkelijk te laten landen bij de beheerders en gebruikers aan klantzijde (aangezien het markdown-bestanden zijn is dat niet lastig).