Zo optimaliseer je technische documentatie en API-docs voor AI-indexering

De meeste developers denken dat API-documentatie voor mensen is. Dat is al niet meer zo.

Als engineers ChatGPT vragen hoe ze zich bij een API authenticeren, een webhook bouwen of met rate limiting omgaan, concurreert jouw documentatie direct met 50 andere bronnen in de beoordeling van het AI-systeem. AI-zoekmachines behandelen technische documentatie als primaire bronnen. Een goed gestructureerde API-referentie kan honderden keren per maand geciteerd worden. Een slecht geoptimaliseerde wordt compleet genegeerd.

Het probleem is dat technische documentatie niet voor AI is gemaakt. Ze is gemaakt voor mensen die in Google zoeken, op links klikken en stap voor stap lezen. AI-systemen lezen anders. Ze halen eruit, knippen in stukken, wijzen toe en citeren. De structuur van je documentatie, je codevoorbeelden en je aanpak voor versiebeheer bepalen alle drie of een AI-systeem je content kan vinden, begrijpen en citeren. In dit hoofdstuk lees je hoe optimalisatie van technische documentatie eruitziet en welke aanpassingen je docs van onzichtbaar tot onmisbaar maken.

Wat is optimalisatie van technische documentatie voor AI?

Optimalisatie van technische documentatie voor AI betekent dat je API-referenties, implementatiegidsen, foutdocumentatie en codevoorbeelden zo opbouwt dat AI-crawlers ze kunnen lezen, eruit kunnen halen, kunnen toewijzen en juist kunnen citeren. Traditionele SEO optimaliseert voor het volgen van links en het matchen van zoekwoorden. Optimalisatie voor AI richt zich op duidelijke betekenis, makkelijk te extraheren tekst en een hoge dichtheid aan feiten.

Een AI-systeem dat je docs indexeert, doet drie dingen. Het crawlt je pagina's om ze te lezen (crawlbaarheid). Het slaat delen van je content op als losse stukken die opgehaald kunnen worden als ze relevant zijn (chunking). En het beslist of het jouw stuk als bron citeert bij het geven van een antwoord (citeerwaardigheid). De meeste documentatie faalt bij een of meer van deze stappen.

Waarom AI-citaties ertoe doen voor technische content

Technische documentatie is een van de contenttypes met het meeste vertrouwen in AI-systemen. Vraagt een developer ChatGPT hoe hij jouw API gebruikt, dan weegt het systeem technische documentatie zwaarder dan blogartikelen of forumdiscussies, omdat API's precisie vragen. Een verkeerd endpoint, een ontbrekende parameter of een onjuiste authenticatiemethode breekt de integratie.

AI-systemen belonen die perceptie. Je API-referentie heeft meer kans om geciteerd te worden dan je blogcontent, omdat ze specifieker, beter te controleren en completer is. Het probleem is dat developers je niet via AI-zoeken ontdekken zoals ze blogcontent ontdekken. Ze vinden je via directe zoekopdrachten naar je API, via mond-tot-mondreclame en als early adopters. Hebben ze je documentatie eenmaal gevonden, dan bepaalt jouw optimalisatie of andere developers je oplossing via AI vinden.

Hoe AI-systemen technische documentatie lezen en eruit halen

AI-crawlers behandelen je documentatie als een gestructureerde database, niet als een verhaal. Dit gebeurt er als een AI-systeem je docs indexeert.

Eerst vraagt de crawler je pagina op (of je documentatieplatform levert hem via een API). Zijn je docs gebouwd op JavaScript-frameworks zonder server-side rendering, dan krijgt de crawler lege HTML. Dit is een van de meest voorkomende fouten. Gebruik je een modern JavaScript-framework voor je docs, controleer dan of je hostingprovider of documentatieplatform pagina's server-side rendert. Anders blijft je content onzichtbaar voor de meeste AI-crawlers.

Ten tweede knipt het systeem je pagina in stukken. Het slaat je API-referentie van 4.000 woorden niet op als één blok. Het deelt haar op in secties, meestal van 100 tot 300 woorden. De hiërarchie van je koppen is hier enorm belangrijk. Sla je koppniveaus over (van een H1 direct naar een H3), dan raakt het systeem in de war over welke content waar hoort. Zijn je koppen vaag ("Overzicht" in plaats van "Authenticatiemethoden"), dan kan het systeem niet zien waar elke sectie over gaat zonder elk woord te lezen.

Ten derde geeft het systeem metadata aan elk stuk. Het leest je kop, de alinea, de codevoorbeelden en de gestructureerde data (schema-markup) om te begrijpen waar het stuk over gaat. Daarna slaat het dat stuk op in een vectordatabase, waar vergelijkbare concepten bij elkaar komen te staan. Stelt een developer een vraag, dan zoekt het systeem de clusters dicht bij die vraagvector en haalt het de meest relevante stukken op.

Ten vierde beslist het systeem of het jouw stuk citeert. Dat hangt af van feitendichtheid, duidelijkheid, specificiteit en of de informatie ook elders bestaat. Een algemene uitleg over het instellen van headers wordt minder vaak geciteerd dan een specifiek voorbeeld dat laat zien welke headers jouw API vereist.

Optimaliseer de structuur van je documentatie voor AI-extractie

De hiërarchie van je koppen is je krachtigste optimalisatiemiddel. Gebruik consistente, specifieke H2- en H3-koppen die het systeem precies vertellen waar elke sectie over gaat.

Gebruik specifieke, volledige koppen

FOUTE kop: "Authenticatie"

GOEDE kop: "Hoe je API-verzoeken authenticeert"

De goede versie vertelt het systeem dat deze sectie bruikbare informatie over authenticatie bevat. De foute versie is dubbelzinnig. Ze kan gaan over waarom authenticatie bestaat, hoe authenticatie werkt of wat je doet als authenticatie mislukt. Wees specifiek.

Laat de koppenstructuur de contenthiërarchie volgen

Heeft je API meerdere authenticatiemethoden (API-sleutel, OAuth, JWT), gebruik dan voor elke methode een H3-subkop, geen opsommingstekens of vetgedrukte tekst. Opsommingstekens zijn prima voor lijsten met items. Ze zijn niet geschikt voor benoemde secties die hun eigen structuur nodig hebben.

Goede structuur

• H2: Hoe je API-verzoeken authenticeert
• H3: Authenticeren met een API-sleutel
• H3: Authenticeren met OAuth 2.0
• H3: Authenticeren met JWT

Deze structuur vertelt het systeem dat authenticatie het hoofdonderwerp is en dat daaronder drie aparte methoden bestaan. Het systeem kan de OAuth-sectie los eruit halen en citeren als een developer specifiek naar OAuth vraagt.

Kondig stappen expliciet aan

Geef je een reeks stappen, kondig ze dan expliciet aan. Ga er niet van uit dat het systeem begrijpt dat je opsommingstekens stappen zijn.

FOUT: "Voeg om te authenticeren je API-sleutel toe aan de requestheader. Gebruik de headernaam Authorization. Geef de waarde de vorm Bearer JOUW_API_SLEUTEL."

GOED: "Om je API-verzoek te authenticeren, volg je deze drie stappen. Zoek eerst je API-sleutel op in de instellingen van je WEMASY-account. Voeg daarna de Authorization-header toe aan je verzoek. Geef de waarde ten slotte de vorm Bearer JOUW_API_SLEUTEL."

De goede versie gebruikt expliciete taal die het systeem vertelt dat dit opeenvolgende stappen zijn, geen losse feiten.

Maak je codevoorbeelden klaar voor extractie

Codevoorbeelden zijn het meest geciteerde contenttype in technische documentatie. AI-systemen citeren graag code, omdat code eenduidig is. Maar niet alle codevoorbeelden zijn gelijk. De manier waarop je code presenteert, bepaalt of het systeem haar juist kan halen en citeren.

Zet voor de code tekst die uitlegt wat de code doet

Zet codeblokken niet los neer. Laat elk codevoorbeeld voorafgaan door een zin die uitlegt wat het laat zien.

FOUTE opbouw
[Codeblok]
[Alinea met uitleg]

GOEDE opbouw
[Zin met uitleg]
[Codeblok]
[Extra context of foutafhandeling]

De uitleg vooraf vertelt het systeem wat het van de code kan verwachten. Ze geeft ook context die het systeem kan citeren voordat de code zelf komt.

Laat voorbeelden over één taak gaan

Laat geen codevoorbeeld van 50 regels zien dat vijf verschillende dingen demonstreert. Splits het op in meerdere voorbeelden die elk één specifiek gedrag laten zien. Een AI-systeem dat een codevoorbeeld eruit haalt, moet er zeker van zijn dat het voorbeeld echt compleet is en niet afhangt van een setup die elders staat.

Neem foutafhandeling op in codevoorbeelden

Echte developers vragen altijd naar fouten. Mist je codevoorbeeld foutafhandeling, dan vragen developers het AI-systeem wat er gebeurt als die code faalt. Beantwoordt je documentatie dat niet, dan citeert het AI-systeem de documentatie van iemand anders die dat wel doet. Neem try-catch-blokken, foutresponsen of expliciete opmerkingen op over welke fouten de bewerking kan geven.

Structureer API-endpoints zo dat AI ze begrijpt

Je referentie van API-endpoints is je belangrijkste documentatie voor AI-citaties. Zorg dat elk endpoint los te begrijpen is, zonder dat lezers tussen pagina's moeten springen.

Begin elk endpoint met wat het doet

Begin een endpointreferentie niet met "Het Users-endpoint geeft gebruikersdata terug." Begin met een volledige zin die de actie uitlegt.

FOUT: "Het endpoint /users geeft toegang tot gebruikersrecords."

GOED: "Haal een lijst op van alle gebruikers in je workspace."

De goede versie is een actie. Ze vertelt het systeem precies wat dit endpoint doet, zonder dat het systeem het uit het pad moet afleiden.

Neem de volledige requeststructuur op in elke endpointsectie

Verwijs niet naar een gedeelde sectie "Authenticatie" in de aanname dat het systeem de informatie zelf combineert. Beschrijf in de documentatie van elk endpoint hoe je authenticeert, welke headers je meestuurt en hoe het complete verzoek eruitziet. Daardoor kan elk endpoint los worden opgehaald.

Laat zowel succes- als foutresponsen zien

Documenteer hoe een geslaagde respons eruitziet. Documenteer daarna hoe foutresponsen eruitzien. Neem van elke veelvoorkomende foutsituatie minstens één voorbeeld op (401 Unauthorized, 404 Not Found, 429 Rate Limited). Heeft een AI-systeem zowel geslaagde als foute responsen, dan kan het developers completere hulp geven.

Ga zo met versies om voor zichtbaarheid bij AI

Veel API's hebben meerdere versies. V1, V2 en soms oudere versies die nog in productie draaien. Versiebeheer geeft AI-systemen een specifiek probleem. Welke versie moet worden geciteerd als iemand naar je API vraagt?

De meeste AI-systemen citeren de nieuwste versie die ze kunnen vinden. Is jouw huidige versie v3, maar maakt je documentatieplatform v1 en v2 even goed vindbaar, dan citeert het systeem misschien de oude versie. Developers krijgen dan verouderde instructies.

Gebruik een URL-structuur die laat zien welke versie voorrang heeft

Host de huidige documentatie waar mogelijk op een nette URL (/docs/api) en zet oudere versies op URL's met een versienummer (/docs/api/v1, /docs/api/v2). Zo laat je AI-systemen zien dat de URL zonder versienummer de huidige, aanbevolen versie is.

Zet versiemeldingen bij oude documentatie

Onderhoud je documentatie voor oudere versies (omdat developers ze nog gebruiken), zet dan bovenaan een duidelijke versiemelding. Ga er niet van uit dat het systeem je URL leest en begrijpt welke versie het bekijkt.

GOEDE melding: "Je bekijkt de documentatie van API v1. Deze versie is verouderd en wordt op 1 januari 2027 verwijderd. We raden aan om te upgraden naar API v3. Zie de upgradegids."

Maak duidelijk dat de versie verouderd is. Noem de einddatum. Link naar de huidige versie en naar een migratiegids. Zo heeft het systeem alles wat het nodig heeft om de verouderde documentatie goed in te passen.

Maak integratiegidsen en tutorials geschikt voor extractie

Integratiegidsen verschillen van API-referenties. Ze zijn verhalend, taakgericht en bedoeld voor developers die specifieke workflows bouwen. AI-systemen citeren ze anders.

Begin met de eindsituatie, niet met de uitleg

Een integratiegids over het bouwen van een webhookontvanger moet openen met hoe een werkende webhookontvanger eruitziet. Laat daarna de stappen zien om hem te bouwen. Laat dan zien hoe je hem test.

Deze volgorde is belangrijk, omdat AI-systemen secties los van elkaar eruit halen. Vraagt een developer "hoe luister ik naar webhook-events", dan haalt het systeem misschien je sectie over webhook-listeners op. Die sectie moet compleet genoeg zijn om op zichzelf te staan.

Gebruik genummerde stappen met expliciete keuzemomenten

Voorwaardelijke logica moet expliciet zijn. Zeg niet "als je events wilt filteren, voeg je deze code toe". Stel in plaats daarvan een directe vraag als kop.

GOEDE opbouw
Stap 1: Maak een webhook-endpoint
Stap 2: Registreer de URL van je endpoint
Stap 3: Verwerk binnenkomende webhooks
Stap 4: Wil je events filteren? (Ja / Nee)
- Zo ja: Voeg eventfiltering toe
- Zo nee: Ga door naar testen
Stap 5: Test je webhook

Door deze structuur ziet het AI-systeem direct waar voorwaardelijke logica zit en welke opties er zijn.

Markeer je documentatie met gestructureerde data

Schema-markup vertelt AI-systemen wat voor soort content ze lezen. Een implementatiegids? Een API-referentie? Een tutorial? Gestructureerde data maakt het doel expliciet.

Gebruik Article-schema voor gidsen en integratiedocumentatie

Alle documentatie die meer is dan een referentiepagina, hoort Article-schema te gebruiken. Neem de auteur, de publicatiedatum en de datum van de laatste wijziging op. Dat helpt het systeem autoriteit en actualiteit te beoordelen.

Gebruik HowTo-schema voor stapsgewijze gidsen

Heeft je documentatie genummerde stappen, gebruik dan HowTo-schema. Geef elke stap een naam en een beschrijving. Zo kan het systeem losse stappen eruit halen en de relevante stap citeren.

Gebruik FAQPage-schema voor veelgestelde vragen

Heeft je documentatie een FAQ-sectie, markeer die dan. Ga er niet van uit dat het systeem haar zelf als FAQ herkent.

Zo ondersteunt WEMASY technische documentatie

De websitebouwer van WEMASY bevat tools die de structuur van technische documentatie eenvoudiger maken. Je zet duidelijke koppenhiërarchieën op, voegt codeblokken met de juiste opmaak toe en organiseert documentatie over meerdere pagina's in een samenhangende structuur. WEMASY regelt ook automatisch server-side rendering, zodat je documentatie volledig crawlbaar is voor AI-systemen. Bekijk wat er in elk abonnement zit.

Veelgestelde vragen