La documentation comme produit

Spec: ISO/IEC/IEEE 26514 Spec: ISO/IEC/IEEE 26513 Spec: ISO 24495-1 Evidence: Standard-backed

En bref

Ces pages suivent un modèle de qualité documentaire, s’appuient sur un langage clair et une hiérarchie de styles à plusieurs niveaux, et sont vérifiées par le même type de contrôles automatisés que ceux qui s’exécutent sur le code du moteur. Cette page présente cette discipline et explique pourquoi un défaut de documentation est consigné comme un défaut d’ingénierie.

Elle s’adresse à un ingénieur expérimenté qui s’est déjà laissé piéger par une documentation péremptoire et invérifiable, et qui veut comprendre ce qui rend celle-ci différente avant de lui faire confiance.

Pourquoi c’est important

On adopte une bibliothèque de documents sur la base de la confiance, et c’est dans la documentation que cette confiance se gagne ou se perd. Une page fausse d’une manière que tu ne peux pas déceler est pire que l’absence de page. Elle transforme ta prudence en confiance mal placée. La défaillance fait surface en production, avec ton nom sur le commit.

La littérature normative est sans détour sur les enjeux. Une information utilisateur bien conçue ne se contente pas de réduire les coûts d’assistance : elle renforce la réputation du produit et de son producteur. Tu y parviens en intégrant les tests de vérification et de validation au développement, pas après coup Spec: ISO/IEC/IEEE 26513, §Foreword . NextPDF prend cela au pied de la lettre : la documentation est une surface produit dotée d’un niveau de qualité, et non une politesse accolée au code.

La version courte

NextPDF soumet cette documentation à un modèle de qualité de l’information explicite, dérivé des critères d’information utilisateur du §8 : une page doit être techniquement exacte, employer un vocabulaire unique et cohérent, être compréhensible par le lecteur qu’elle vise, ne contenir que le nécessaire sans omettre ce qui est requis, et rester accessible aux technologies d’assistance Spec: ISO/IEC/IEEE 26514, §8 .
La structure ne s’improvise pas. Les sujets sont organisés en une hiérarchie figée assortie de métadonnées (section, public, niveau de preuve), afin qu’un lecteur repère un sujet par reconnaissance Spec: ISO/IEC/IEEE 26514, §9 , et l’énoncé le plus important figure près du début de chaque page Spec: ISO 24495-1, §5 .
Le ton est régi par une hiérarchie de styles ratifiée — Apple pour le ton, Microsoft pour la procédure, Google pour le code, et un langage clair pour l’ensemble — consignée dans le dépôt, avec la clause amont remplacée par chaque divergence.
La qualité est vérifiée par la machine. Vale applique les packs de ton ; un ensemble de contrôles composer docs:* garantit l’intégrité des liens, l’hygiène des citations, l’absence de texte normatif reproduit mot pour mot et l’absence de fuite de détails privés.
La documentation est développée avec le code, de façon itérative — chaque modification livre sa documentation, pas un arriéré de documentation Spec: ISO/IEC/IEEE 26515, §Introduction .

L’approche de NextPDF

Un modèle de qualité, formalisé par écrit

« Une bonne documentation » reste invérifiable tant que tu n’en nommes pas les attributs. NextPDF reformule les critères d’information utilisateur du §8 dans ses propres termes, comme la référence à laquelle chaque page Insider_ est évaluée : chaque page doit être techniquement exacte, s’en tenir à un vocabulaire unique et cohérent, être compréhensible par le lecteur qu’elle vise, ne contenir que ce dont ce lecteur a besoin sans rien omettre de requis, et rester accessible aux technologies d’assistance Spec: ISO/IEC/IEEE 26514, §8 . Ce ne sont pas des adjectifs ; ce sont des critères de revue. Le test « nécessaire mais complet » explique pourquoi une page énonce sa limite et s’arrête, plutôt que de meubler. La cohérence du vocabulaire explique pourquoi la terminologie est encadrée (ci-dessous). L’accessibilité explique pourquoi chaque composant est utilisable au clavier et avec un lecteur d’écran, et ne transmet jamais une information par la seule couleur.

Une structure par analyse, pas par goût

La taxonomie Insider_ est figée avant la rédaction de la moindre page. C’est délibéré. La norme ISO 26514 exige que l’analyse du public et des tâches précède la conception de l’information Spec: ISO/IEC/IEEE 26514, §9 . Elle exige aussi que les sujets soient organisés en hiérarchies ou en groupes, chacun portant des métadonnées qui identifient son public et son type d’information, afin que les utilisateurs trouvent rapidement ce dont ils ont besoin Spec: ISO/IEC/IEEE 26514, §9 . Dans ce dépôt, ces métadonnées sont du front-matter concret — section, audience, evidence_level, tags — et la carte des clusters tient dans un seul fichier figé. Un lecteur choisit une page par reconnaissance ; il n’a jamais à se souvenir d’un slug.

Dans chaque page, l’ordre est fixe et identique partout, et l’énoncé le plus utile est placé là où un lecteur le trouvera en premier — le plus souvent au début Spec: ISO 24495-1, §5 . C’est pourquoi chaque page Insider_ place La version courte avant le détail : un lecteur peut s’arrêter après trois sections et repartir tout de même avec une réponse défendable.

Une hiérarchie de styles avec preuves à l’appui

Le ton n’est pas laissé à l’humeur du rédacteur. Le dépôt contient une feuille de dérogations ratifiée (docs/style/nextpdf-overrides.md) qui superpose Apple (ton), Microsoft MSTP (procédure et termes d’interface) et Google DDSG (code et CLI) à des bases de langage clair et de vocabulaire contrôlé, avec une table de résolution des conflits par mode. La règle la plus stricte prévaut sur toutes les autres : aucun texte d’un organisme de normalisation sous licence ne doit être reproduit mot pour mot. Point capital : chaque endroit où NextPDF diverge d’un guide amont est consigné avec la clause amont qu’il remplace et la raison. La feuille de style cite ses propres sources de la même manière qu’une page.

Une qualité que tu n’es pas obligé de croire sur parole

La discipline est imposée par l’outillage, et non par les bonnes intentions :

Scaffold The page starts from a populated front-matter and section skeleton.
Vale packs Apple, MSTP, Google, and controlled-vocabulary rules run on the prose.
Link check docs:link-check rejects link rot against the built site.
NDA scan docs:nda-scan rejects private FQCNs and internal artefact names.
Quote fingerprint docs:jaccard-fingerprint flags verbatim standards-text reuse.
Citation audit docs:rag-citation-check / docs:rag-fallback-check guard the digests.
Review A reviewer confirms the page's declared evidence level holds.

Les contrôles de qualité de la documentation, dans l'ordre où une page les franchit : un squelette pré-rempli fixe la structure ; Vale fait respecter les packs de ton ; les contrôles docs :* garantissent l'intégrité des liens, l'hygiène des citations, l'absence de texte normatif reproduit mot pour mot et l'absence de fuite privée ; la revue confirme la base de preuve. Une page qui échoue à un contrôle est un défaut, traité comme un test en échec.

Ces contrôles correspondent à de véritables entrées dans le composer.json de ce dépôt. docs:lint exécute localement les contrôles NDA et les contrôles de liens. docs:jaccard-fingerprint signale les reprises mot pour mot de textes normatifs au-delà d’un seuil de similarité. docs:rag-fallback-check est un garde-fou du protocole d’intégrité des citations, entièrement implémenté, hors ligne et déterministe. La revérification RAG en direct (docs:rag-citation-check) et certains scanners sont configurés comme garde-fous, mais leurs implémentations exhaustives sont encore en cours de développement. L’énoncé honnête est le suivant : le contrat est ratifié et les contrôles structurels sont appliqués aujourd’hui ; le chantier visant à rendre chaque contrôle exhaustif se poursuit. Insider_ ne revendique pas un tableau de bord vert qu’il n’a pas obtenu — ce qui applique à cette page le critère « correct » du modèle de qualité.

Ce que disent les preuves

Cette page est Evidence: Standard-backed pour les affirmations sur la qualité documentaire, et fondée sur le dépôt pour les affirmations relatives à l’application des contrôles. Cette double base est délibérée : les principes viennent des normes ; l’application des contrôles se vérifie en lisant le dépôt.

Affirmation	Base	Ancrage
La documentation a un niveau de qualité défini	Norme	Exactitude, vocabulaire unique, compréhension par le lecteur, nécessité sans omission, accessibilité aux technologies d’assistance Spec: ISO/IEC/IEEE 26514, §8
La terminologie est encadrée	Norme	Terminologie cohérente dans tout l’ensemble d’information Spec: ISO/IEC/IEEE 26514, §8
La structure précède la rédaction	Norme	Analyse du public et des tâches avant la conception Spec: ISO/IEC/IEEE 26514, §9
L’énoncé le plus utile vient en premier	Norme	Message le plus important au début Spec: ISO 24495-1, §5
La documentation est livrée avec le code	Norme	Les livrables de chaque itération incluent l’information utilisateur Spec: ISO/IEC/IEEE 26515, §Introduction
La qualité est vérifiée par la machine	Dans le dépôt	Contrôles `composer.jsondocs:*` ; le `docs/style/nextpdf-overrides.md` ratifié ; la configuration Vale active

Exemple pratique

La discipline se manifeste jusqu’à la plus petite échelle : une donnée de qualité n’est jamais saisie à la main dans la prose, car un chiffre dans la prose devient silencieusement obsolète. Elle est exposée par un composant qui refuse d’inventer une valeur et qui s’appuie sur la base de preuve de la page :

<?php

declare(strict_types=1);

// Illustrative: the documentation build's contract for a quality datum.
// The component throws if no real value is supplied — a metric is never
// allowed to live as a hardcoded literal that can drift out of date.
final class QualityDatum
{
    public function __construct(
        public readonly string $label,
        public readonly string $value,
    ) {
        if ($this->value === '') {
            throw new \InvalidArgumentException(
                'A quality datum must carry a verified value; '
                . 'documentation never invents a metric.',
            );
        }
    }
}

$phpstanLevel = new QualityDatum(label: 'PHPStan', value: 'Level 10');

L’essentiel, c’est le throw. Le critère « exact » du modèle de qualité de l’information n’est pas une simple indication ici ; il est imposé structurellement, de sorte qu’un chiffre obsolète ne puisse pas être livré discrètement.

Idée fausse répandue

Le piège consiste à lire « la documentation comme produit » comme un slogan de surface — une prose plus soignée, des pages plus jolies. C’est tout l’opposé du cosmétique. Cela signifie que la documentation porte un niveau de qualité défini, un vocabulaire encadré, une structure figée et des contrôles vérifiés par la machine, et qu’une page qui échoue à l’un d’eux est un défaut assorti d’un correctif, traité comme un test en échec. La finition est un sous-produit de la discipline, pas son but.

Le second piège consiste à supposer que chaque contrôle est déjà exhaustif sous prétexte que le contrat existe. Ce n’est pas le cas, et cette page le dit clairement. Les contrôles structurels sont appliqués aujourd’hui ; les vérificateurs plus poussés sont en cours de développement. Prétendre le contraire violerait le modèle même de qualité que cette page décrit.

Limites et périmètre

Cette page décrit la discipline de documentation. Elle n’est pas la feuille de style, le fichier de taxonomie, ni les implémentations des contrôles elles-mêmes. Elle n’affirme aucun comportement du moteur. Les artefacts qui font autorité sont dans le dépôt (docs/style/nextpdf-overrides.md, la taxonomie figée, les scripts composer.json docs:*) et l’emportent sur tout résumé présenté ici en cas de divergence.

Le périmètre d’application est partiel, de l’aveu même de ses auteurs. Le contrôle de repli sur l’intégrité des citations est en service. Les contrôles de liens et de NDA s’exécutent en local. Les vérificateurs de citation mot pour mot et de citation en direct sont câblés, mais leurs implémentations exhaustives sont encore en cours de mise en place. Ceci est signalé comme en cours, et non comme achevé. Là où cette page touche à la documentation de la formule Premium, la discipline décrite s’applique au niveau du processus, jamais au niveau d’un quelconque mécanisme non public.

Documentation connexe

Discipline de citation — la règle la plus stricte de la hiérarchie de styles, et le système de niveaux de preuve sur lequel cette page s’appuie.
Le paysage normatif — les normes que cette discipline cite, et la manière dont une clause devient un comportement documenté.
La philosophie de conception de NextPDF — la logique d’ingénierie qui traite un défaut de documentation comme un défaut de code.

Glossaire

Modèle de qualité de l’information — la reformulation par NextPDF des critères d’information utilisateur du §8 de l’ISO 26514 (exact, vocabulaire unique, compréhensible par le lecteur, nécessaire mais complet, accessible aux technologies d’assistance), utilisée comme référence de revue pour chaque page Insider_.
Langage clair — une communication dont la formulation, la structure et la conception permettent aux lecteurs visés de trouver, comprendre et utiliser le contenu ; une base appliquée à tous les modes, et non un type de contenu.
Hiérarchie de styles — l’ensemble ratifié et superposé de guides de style amont (Apple, Microsoft, Google, plus des bases de langage clair et de vocabulaire contrôlé), où chaque divergence de NextPDF est consignée par rapport à sa source.
Contrôle de qualité — une vérification automatisée (un pack Vale ou un script composer docs:*) qu’une page doit franchir ; un échec est un défaut de documentation, pas une vétille.
Métadonnées de front-matter — l’en-tête lisible par la machine (section, audience, evidence_level, tags) qui rend une page localisable et classable, conformément à l’exigence d’organisation des sujets.