Zo is de documentatie van NextPDF opgebouwd

In het kort

Het handboek van NextPDF volgt een vast contract. Elke pagina heeft één onderwerp, één Diataxis-modus en één paginasoort. Elke paginasoort heeft een verplichte set koppen van niveau 2. Een beperkte set manifesten en poorten houdt de structuur consistent terwijl het handboek groeit.

Deze pagina schetst dat systeem, zodat je je bijdrage op de juiste plek kunt plaatsen. Het volledige normatieve contract, inclusief de exacte lijsten met koppen, de regels voor citatieniveaus en de procedure voor poortaansluiting, staat in het interne governancedocument docs/style/expansion-standard.md. Lees eerst deze pagina. Raadpleeg dat document tijdens het schrijven.

Een paginasoort kiezen

Pas deze regels op volgorde toe om te bepalen of je een pagina toevoegt of een bestaande pagina uitbreidt:

1. Als het materiaal een afzonderlijk onderwerp is dat een lezer niet op de bestaande pagina zou verwachten, voeg je een nieuwe pagina toe.
2. Als het materiaal een onderwerp afrondt dat de bestaande pagina al behandelt, breid je die pagina uit.
3. Als het materiaal zo gedetailleerd is dat het een installatie-, snelstart- of taakpagina te omvangrijk zou maken, verplaats je het naar een aparte pagina en verwijs je ernaar.
4. In alle andere gevallen breid je de bestaande pagina uit.

Zodra duidelijk is dat de pagina nodig is, stel je de Diataxis-modus ervan in. De modus bepaalt de paginasoort:

• Een tutorial begeleidt iemand die iets aan het leren is. Gebruik een taakgids die als een recipe is geschreven.
• Een how-to helpt een bekwame lezer een taak te voltooien. Gebruik een taakgids, een server-API-gids of een SDK-gids.
• Referentie geeft exacte feiten weer. Gebruik een API-referentie of een indexpagina.
• Uitleg bouwt begrip op. Gebruik een ontwikkelaarsgids of een gids voor een premiumfunctie.

Duidelijke taal vormt de basis van elke modus; het is geen aparte modus.

De catalogus van paginasoorten

Het handboekcontract kent deze soorten. Hergebruik een bestaande soort wanneer je pagina een API-tabel bevat. Voer alleen bij een pagina zonder API-tabel een nieuwe soort in die uitsluitend uit een label bestaat.

• Indexsoorten: section-index, api-index, extension-index.
• Referentiesoort: api-reference. Hergebruik deze voor elke pagina met de standaard-API-tabel, inclusief server- en Python SDK-referenties.
• Uitlegsoort: developer-guide. Hergebruik deze voor tekst over architectuur, levenscyclus en uitbreidingspunten, inclusief server- en Python SDK-gidsen.
• Nieuwe soorten die alleen uit een label bestaan: premium-feature-guide en task-guide, beide voor pagina’s zonder API-tabel.

Elke pagina begint met ## At a glance. Elke api-reference-pagina bevat de gedeelde API-tabel en de kop Development notes. Verplichte koppen zijn koppen van niveau 2, elk op een eigen regel. Je mag daaronder extra koppen toevoegen.

Checklist voor schrijven

Wanneer je een pagina schrijft, volg je beide checklists. De interne standaard legt elk item normatief vast en verwijst naar de bijbehorende ondersteunende standaard.

Ontwikkelaarsvriendelijkheid:

• Haal uitvoerbare voorbeelden uit examples/ of tests/Cookbook en geef elk afgebakend blok een title=-infostring.
• Vermeld de vereisten in de front-matter en in de inleiding.
• Toon de verwachte uitvoer voor elk voorbeeld dat uitvoer produceert.
• Zorg dat blokken klaar zijn om te kopiëren en te plakken: één taal per blok, volledige namen bij het eerste gebruik en geen prompttekens aan het einde.
• Toon code die standaard veilig is: productievoorbeelden gebruiken try/catch met de meest specifieke NextPDF-uitzondering en nooit een lege catch.
• Sluit af met vervolglinks en stel in de front-matter related: in.

Vertaalgereedheid:

• Schrijf één idee per zin, zodat machinevertaling beheersbaar blijft.
• Houd koppen en labels kort, omdat de meeste doeltalen uitdijen.
• Vermijd idiomen.
• Houd symboolnamen, configuratiesleutels, CLI-vlaggen en uitzonderingsnamen in codeopmaak; standaardnamen zoals PDF/A-4, PAdES en eIDAS worden nooit vertaald.
• Stel i18n_ready en xliff_segments naar waarheid in en schrijf in Unicode NFC.

Volg voor toon, codevoorbeelden, terminologie en citatiestijl het goedgekeurde stijl-overrideblad waarnaar de interne standaard verwijst.

Poortaansluiting

Sluit een nieuwe pagina aan volgens deze volgorde:

1. Maak de basisstructuur van de pagina zodat de front-matter overeenkomt met het siteschema.
2. Schrijf de inhoud volgens de verplichte koppen van de paginasoort.
3. Voeg een { path, owner, kind, headings[] }-vermelding toe aan docs/manual-contract.json. Het pad is relatief ten opzichte van src/content/docs, gebruikt forward slashes en bevat geen voorloopslash en geen ...
4. Voeg voor een API-referentie de symbolen van de pagina toe aan docs/api-coverage-manifest.json; elk symbool moet op de pagina voorkomen en in de broncode bestaan.
5. Werk docs/source-manifest.json alleen bij wanneer de pagina uit een nieuwe bronrepository komt.
6. Voeg de pagina als expliciete vermelding toe aan de juiste zijbalkgroep in astro.config.mjs.
7. Voeg een rij voor locale-dekking toe waarin alle zeventien locale-cellen zijn ingesteld op missing voor een pagina die alleen in het Engels bestaat.
8. Voer de documentatiepoorten, de build en het prestatiebudget uit.

Pagina’s die door de site worden beheerd, staan onder src/content/docs, hebben owner op nextpdf-docs staan en hebben nooit een aggregatiemarkering. Geaggregeerde pagina’s komen uit een bronrepository. Hun publish-vlag staat in de front-matter van de bron, dus bewerk je ze daar en niet hier.

Zie ook

• Integraties: het grootste uitgewerkte voorbeeld van de handboekstructuur over meerdere packages heen.
• Het interne governancedocument docs/style/expansion-standard.md bevat het volledige contract: de exacte lijsten met koppen voor elke paginasoort, de regels voor citatieniveaus en de volledige procedure voor poortaansluiting.