Winst:
- Mogelijkheid om README-, docstring- en changelog-concepten te produceren op basis van doelgroep en bron met AI
- Mogelijkheid om de 'wat/hoe'- en 'waarom'-lagen in documentatie te scheiden en het 'waarom' als mens toe te voegen
- Het verifiëren van de installatiestappen door ze persoonlijk uit te voeren en het document onderdeel te maken van de codewijziging
Het vaakst verwaarloosde maar langstlevende onderdeel van software is documentatie. De code is zelfs na maanden nog leesbaar; De persoon die het heeft geschreven is verdwenen, de context is vergeten en alleen wat er is geschreven blijft over. Een goede README (inleidend document dat uitlegt wat een project is en hoe je het installeert en uitvoert), verklarend codecommentaar en een up-to-date API-documentatie (een referentie waarin wordt uitgelegd hoe je een interface gebruikt) bepaalt direct de snelheid van een team. AI haalt een groot deel van de 'schrijfmoeheid' uit de documentatie, maar er zit ook een valkuil aan: AI kan uit code afleiden wat het doet, maar weet vaak niet waarom het op die manier wordt gedaan.
In deze unit leer je hoe je README, codecommentaar, docstring (commentaarblok geschreven per functie/klasse), API-document en changelog kunt produceren met AI; en hoe je op menselijke wijze het meest waardevolle deel van de documentatie kunt behouden: het ‘waarom’.
Onderscheid tussen "Wat" en "Waarom"
Er zijn twee lagen van documentatie. De eerste is wat/hoe: "deze functie sorteert een lijst", "voer deze opdracht uit om te installeren". Deze kunnen uit de code en structuur worden gehaald; AI blinkt hier uit. Ten tweede, waarom: "waarom hebben we deze dienst asynchroon gemaakt in plaats van synchroon", "waarom is deze grenswaarde 30 seconden", "waarom hebben we deze bibliotheek boven de andere gekozen". Deze staan niet in de code; Het is het product van ontwerpbeslissingen, beperkingen en pijn uit het verleden.
AI weet niet "waarom"; In het beste geval vormt het een redelijke inschatting – wat gevaarlijk is, omdat een verkeerde reden erger is dan helemaal geen reden. De taakverdeling is dus duidelijk: AI stelt het ‘wat/hoe’ op, jij voegt het ‘waarom’ toe. De meest waardevolle opmerking is degene die zegt wat de code niet kan zeggen.
Tip: Herhaal niet met een opmerking wat de code zelf duidelijk zegt (zoals i = i + 1 // verhoog i met één). AI produceert soms zulke overbodige opmerkingen; Elimineer ze en besteed je energie aan ‘waarom’-opmerkingen.
Stap voor stap: documentatie genereren met AI
- Specificeer de doelgroep. ‘Een ontwikkelaar die net begint’, ‘het externe team dat deze API gaat gebruiken’, ‘de toekomstige ik’ – het publiek zet de toon voor taal en diepgang.
- Geef de bron. Voeg de relevante code, bestaande README, voorbeeldgebruik toe aan de prompt. Een document zonder bron is een uitnodiging tot verzinsel.
- Impositiestructuur. Standaardsecties voor README (Doel, Installatie, Gebruik, Configuratie, Bijdrage), projectformaat voor docstring.
- Markeer de "waarom"-ruimtes. Vraag de AI om beslissingen waarvan zij de reden niet kent te markeren als “hier is een ‘waarom’-notitie vereist”; Vervolgens vul je die lege plekken in.
- Verifiëren. Voer de installatiestappen daadwerkelijk uit; probeer de voorbeeldcode. Een README die niet werkt, is erger dan helemaal geen README.
Drie mini-hoesjes
Geval 1 — README versnelde de onboarding. De README van een open source-tool ontbrak; Nieuwe bijdragers hadden gemiddeld twee uur moeite met de installatie. Het team gaf de installatiescripts en package.json aan AI en stelde een gestructureerde README op, voerde vervolgens de stappen zelf uit op een schone machine en voegde de twee ontbrekende afhankelijkheden toe. De installatietijd voor volgende bijdragers daalde tot gemiddeld 25 minuten.
Geval 2 – De verzonnen ‘waarom’-valkuil. Een ontwikkelaar vroeg de AI om commentaar naast een time-outwaarde (time-out=30). De AI schreef een redelijke maar onjuiste rechtvaardiging "om een hoge netwerklatentie te tolereren"; de echte reden was de contractuele limiet van 30 seconden van een downstream-service. De verkeerde interpretatie leidde ertoe dat een volgende ontwikkelaar de waarde onnodig verhoogde, wat tot een incident leidde. Les: de code-eigenaar moet de rechtvaardiging verifiëren.
Geval 3 — De Docstring-standaard is geautomatiseerd. Een hulpmodule met 40 functies had geen docstrings. De AI kreeg het projectformaat (Google-stijl) en produceerde voor elke functie parameter-, return- en uitzonderingsbeschrijvingen; De ontwikkelaar heeft deze beoordeeld en een aantal onjuiste typeverklaringen gecorrigeerd. Het documenteren van 40 functies ging van ongeveer een halve dag naar een uur.
Vier kopieerbare sjablonen
Gestructureerd README-concept:
Doelgroep: {{bijv. nieuwe bijdrager}}.Schrijf een concept-README op basis van de onderstaande bestanden. Secties: Doel, Functies, Vereisten, Installatie, Bediening, Configuratie, Testen, Bijdrage. Extraheer installatie-/uitvoeropdrachten uit daadwerkelijke bestanden; PASSEND. Markeer de plaatsen waarvan u het niet zeker weet met "[VERIFY]". Bron: {{package.json / scripts / voorbeeldcode}}
Docstring/API-referentie:
Schrijf docstring naar deze functies in {{projectstijl: Google/NumPy/JSDoc}} formaat: korte samenvatting, parameters (type + betekenis), return, gegenereerde uitzonderingen, 1 kort voorbeeld. Herhaal niet wat de code DUIDELIJK zegt. Markeer ontwerpbeslissingen die 'waarom' vereisen als '[WAAROM NOODZAKELIJK]', schrijf geen verzonnen rechtvaardiging.{{code}}
Verwijder spaties voor de opmerking 'waarom':
In deze code zou de volgende ontwikkelaar zich kunnen afvragen: "Waarom is dit zo?" (magische cijfers, ongebruikelijke beslissingen, oplossingen). Geef voor elk een commentaar SKELET, maar laat de reden BLANK; Ik zal de motivering invullen.{{code}}
Changelog/PR-verklaring:
Schrijf een {{changelog entry / PR description}} uit de onderstaande diff. Formaat: wat is er veranderd (in gebruikerstaal), waarom (probleem: {{...}}), belangrijke wijziging (indien aanwezig), is deze getest. Pas het technische jargon aan de doelgroep aan.{{diff}}
Zwakke prompt/sterke prompt
Zwak: "Schrijf een README voor dit project."
Strong: "Doelgroep: een ontwikkelaar die deze repository voor de eerste keer kloont. Gebaseerd op de bijgevoegde package.json, docker-compose.yml en scripts/ map, schrijf een concept-README met de secties Doel, Vereisten, Installatie, Bediening, Testen en Bijdrage. Pak de opdrachten uit deze bestanden, verzin ze niet; markeer overal waar je het niet zeker weet met [VERIFY]."
De sterke versie geeft het publiek, de bron, de structuur en de ‘maak het, markeer het’-regel; zodat het document gebaseerd is op echte bestanden en de te verifiëren plaatsen duidelijk zichtbaar zijn.
Documenttype
AI doet het goed
Mens voegt toe/verifieert
README-installatie
stap overzicht
Voer de stappen uit en bevestig
Docstring/API
Structuur, parameter, type
Juiste type en "waarom"
Codeer commentaar
Samenvatting van 'Wat hij doet'
"Waarom is dit" rechtvaardiging
Wijzigingslog/PR
eerste ontwerp
Impact en nauwkeurigheid
Bouwkundige beslissing (ADR)
skelet
Echte beslissingen en compromissen
Documentatie vereist onderhoud
Het gevaarlijkste aspect van een document is wanneer het waar lijkt, ook al is het onwaar. Wanneer de code verandert en het document niet wordt bijgewerkt, wordt de lezer actief misleid. AI maakt updaten eenvoudig: geef een diff op en vraag “op welke delen van het document is deze wijziging van toepassing?” je mag het vragen. Maar het is het proces dat zorgt voor up-to-dateheid: maak de documentatie-update onderdeel van de codewijziging (het acceptatiecriterium van PR). AI versnelt; Het team bouwt aan discipline.
Let op: Publiceer niet zonder de installatiestappen in een README te verifiëren. Een 'waarschijnlijk werk'-document kan de eerste dag van een nieuwe ontwikkelaar verpesten en het vertrouwen aantasten. Voer de stappen zelf uit in een schone omgeving.
Veel voorkomende fouten
- Het ‘waarom’ zo krijgen dat het bij de AI past. Valse rechtvaardiging is erger dan geen rechtvaardiging; De code-eigenaar moet de ontwerpreden schrijven.
- De installatiestappen worden niet geverifieerd. README die niet werkt, vernietigt het vertrouwen.
- Onnodige opmerking waarbij de code wordt herhaald. Het produceert ruis, waardoor echte ‘waarom’-interpretaties aan het zicht worden onttrokken.
- Zonder de doelgroep te specificeren. Een document waarvan niet duidelijk is voor wie het is geschreven, heeft noch voor de beginneling, noch voor de deskundige nut.
- Het scheiden van de update van het proces. Als het document niet wordt bijgewerkt met de code, wordt het snel misleidend.
Samengevat
AI haalt een groot deel van de mechanische last uit de documentatie: snelle concepten README, docstring, API-referentie, changelog en PR-beschrijvingen. Maar het kan het ‘waarom’, de meest waardevolle laag, niet kennen, en het is gevaarlijk om dat te verzinnen. De taakverdeling is duidelijk: AI produceert het ‘wat/hoe’, jij voegt het ‘waarom’ toe. Specificeer het publiek, zorg voor hulpmiddelen, leg structuur op, markeer geschikte plaatsen en verifieer elke installatiestap door deze zelf uit te voeren. Maak documentatie een integraal onderdeel van de codewijziging.
Applicatie taak
Kies een module of klein project waarvan de documentatie ontbreekt of verouderd is. Genereer eerst een schets uit AI met de “gestructureerde README draft” (of docstring) sjabloon; Zorg ervoor dat u de bron en de doelgroep vermeldt. Doorloop vervolgens elk punt waar de AI [VERIFY] of [WHY NEEDED] heeft gemarkeerd: voer daadwerkelijk de installatiestappen uit en vul het ontwerp ‘waarom’ in met je eigen kennis. Noteer hoeveel stappen er moeten worden opgelost en hoeveel ‘waaroms’ je hebt toegevoegd.
controlelijst
- [ ] In de documentatie maak ik onderscheid tussen de lagen "wat/hoe" en "waarom".
- [ ] Ik laat de AI het ‘waarom’ niet verzinnen, ik voeg het zelf toe.
- [ ] Ik geef als prompt de doelgroep en de daadwerkelijke bronbestanden.
- [ ] Ik verifieer de [VERIFY] punten gemarkeerd door de AI door ze persoonlijk uit te voeren.
- [ ] Ik elimineer onnodige opmerkingen die de code herhalen.
- [ ] Ik maak de documentatie-update onderdeel van de codewijziging.