Structure de la documentation NextPDF

En bref

Le manuel NextPDF évolue selon un contrat fixe. Chaque page a un seul sujet, un seul mode Diataxis et un seul type de page. Chaque type de page possède un ensemble requis de titres de niveau 2. Un petit nombre de manifestes et de gates maintiennent la cohérence de la structure à mesure que le manuel s’étend.

Cette page te présente la forme de ce système afin que ta contribution arrive au bon endroit. Le contrat complet et normatif, qui inclut les listes exactes de titres, les règles de citation et la procédure pas à pas de branchement aux gates, se trouve dans le document de gouvernance interne docs/style/expansion-standard.md. Lis d’abord cette page ; consulte ce document quand tu rédiges.

Choisir un type de page

Applique cette règle, dans l’ordre, pour décider s’il faut ajouter une page ou en étendre une :

1. Si le contenu est un sujet distinct qu’un lecteur ne s’attendrait pas à trouver sur la page existante, ajoute une nouvelle page.
2. Si le contenu complète un sujet que la page existante couvre déjà, étends cette page.
3. Si le contenu est un détail approfondi qui gonflerait une page d’installation, de démarrage rapide ou de tâche, déplace-le vers une page séparée et fais-y un lien.
4. Sinon, étends la page existante.

Une fois que tu sais que la page doit exister, définis son mode Diataxis, qui détermine le type de page :

• Le tutoriel accompagne un apprenant, alors utilise un guide de tâche rédigé comme un recipe.
• Le how-to aide un lecteur compétent à terminer une tâche, alors utilise un guide de tâche, un guide d’API serveur ou un guide SDK.
• La référence énonce des faits exacts, alors utilise une référence d’API ou une page d’index.
• L’explication construit la compréhension, alors utilise un guide développeur ou un guide de fonctionnalité premium.

Le langage clair est la base dans chaque mode, pas un mode à part entière.

Le catalogue des types de page

Le contrat du manuel reconnaît ces types. Réutilise un type existant chaque fois que ta page comporte une table d’API ; n’introduis un nouveau type d’étiquette seule que pour une page sans table d’API.

• Types d’index : section-index, api-index, extension-index.
• Type de référence : api-reference. Réutilise-le pour toute page comportant la table d’API standard, y compris les références serveur et SDK Python.
• Type d’explication : developer-guide. Réutilise-le pour la prose d’architecture, de cycle de vie et de point d’extension, y compris les guides serveur et SDK Python.
• Nouveaux types d’étiquette seule : premium-feature-guide et task-guide, tous deux pour les pages sans table d’API.

Chaque page commence par ## At a glance. Chaque page api-reference comporte la table d’API partagée et le titre Development notes. Les titres requis sont exactement de niveau 2, chacun sur sa propre ligne ; tu peux ajouter d’autres titres en dessous.

Liste de contrôle de rédaction

Quand tu rédiges une page, veille à satisfaire ces deux listes de contrôle. Le standard interne énonce chaque point de manière normative et renvoie au standard sur lequel il repose.

Convivialité pour les développeurs :

• Tire les exemples exécutables de examples/ ou de tests/Cookbook, et donne à chaque bloc délimité une chaîne d’info title=.
• Énonce les prérequis dans le front-matter et dans l’introduction.
• Montre la sortie attendue pour tout échantillon qui en produit une.
• Garde les blocs prêts au copier-coller : un seul langage par bloc, les noms complets à la première utilisation, aucun caractère d’invite en fin de ligne.
• Montre du code sécurisé par défaut : les échantillons de production utilisent try/catch avec l’exception NextPDF la plus spécifique et jamais de catch vide.
• Termine par des liens de poursuite et définis related: dans le front-matter.

Préparation à la traduction :

• Écris une seule idée par phrase pour éviter de faire déraper la traduction automatique.
• Garde les titres et les étiquettes courts, car la plupart des langues cibles sont plus longues.
• Évite les idiomes.
• Garde les noms de symboles, les clés de configuration, les options de CLI et les noms d’exception en format de code ; les noms de standards comme PDF/A-4, PAdES et eIDAS ne sont jamais traduits.
• Définis i18n_ready et xliff_segments honnêtement, et écris en Unicode NFC.

Pour le style de voix, les échantillons de code, la terminologie et les citations, suis la feuille de surcharge de style ratifiée référencée depuis le standard interne.

Branchement aux gates

Une nouvelle page se branche selon une procédure ordonnée :

1. Échafaude la page pour que son front-matter corresponde au schéma du site.
2. Rédige le corps selon les titres requis par le type de page.
3. Ajoute une entrée { path, owner, kind, headings[] } à docs/manual-contract.json. Le chemin est relatif à src/content/docs, utilise des barres obliques et ne porte ni barre oblique initiale ni ...
4. Pour une référence d’API, ajoute les symboles de la page à docs/api-coverage-manifest.json ; chaque symbole doit apparaître dans la page et exister dans le source.
5. Mets à jour docs/source-manifest.json uniquement quand la page provient d’un nouveau dépôt source.
6. Ajoute la page au bon groupe de barre latérale dans astro.config.mjs en tant qu’entrée explicite.
7. Ajoute une ligne de couverture de locale avec les dix-sept cellules de locale réglées sur missing pour une page en anglais uniquement.
8. Exécute les gates de documentation, le build et le budget de performance.

Les pages appartenant au site vivent sous src/content/docs, fixent owner à nextpdf-docs et ne portent jamais de marqueur d’agrégation. Les pages agrégées proviennent d’un dépôt source, et leur indicateur de publication vit dans le front-matter source ; c’est donc là-bas que tu les modifies, pas ici.

Voir aussi

• Intégrations : le plus grand exemple concret de la forme du manuel à travers de nombreux packages.
• Le document de gouvernance interne docs/style/expansion-standard.md contient le contrat complet : les listes exactes de titres pour chaque type de page, les règles de citation et la procédure complète de branchement aux gates.