Documentatie als product

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

In het kort

Deze pagina’s zijn opgebouwd volgens een documentatiekwaliteitsmodel, geschreven binnen een basislijn voor eenvoudige taal en een gelaagde stijlhiërarchie, en gecontroleerd door hetzelfde soort geautomatiseerde poorten die ook op de enginecode draaien. Deze pagina legt die discipline uit en waarom NextPDF een documentatiedefect registreert als een engineeringdefect.

Ze is geschreven voor een senior engineer die zijn vingers heeft gebrand aan stellig klinkende, niet-verifieerbare documentatie en wil weten wat deze documentatie anders maakt voordat hij erop vertrouwt.

Waarom dit belangrijk is

Een documentbibliotheek wordt gekocht op basis van vertrouwen, en in de documentatie wordt dat vertrouwen gegeven of ingetrokken. Een pagina die fout is op een manier die je niet kunt opmerken, is erger dan helemaal geen pagina. Ze zet je voorzichtigheid om in misplaatst vertrouwen. De fout duikt op in productie, met jouw naam op de commit.

De normliteratuur is onomwonden over wat er op het spel staat. Goed ontworpen gebruikersinformatie doet meer dan de ondersteuningskosten verlagen; ze versterkt de reputatie van het product en zijn maker. Dat verdien je door verificatie- en validatietesten in de ontwikkeling op te nemen, niet pas erna Spec: ISO/IEC/IEEE 26513, §Foreword . NextPDF neemt dat letterlijk: documentatie is een productoppervlak met een kwaliteitslat, niet een extraatje dat aan de code is gekoppeld.

De korte versie

NextPDF houdt deze documentatie aan een expliciet informatiekwaliteitsmodel dat is afgeleid van de §8-criteria voor gebruikersinformatie: een pagina moet technisch correct zijn, één consistente woordenschat gebruiken, begrijpelijk zijn voor de aangewezen lezer, alleen zeggen wat nodig is en toch niets noodzakelijks weglaten, en bereikbaar blijven voor hulptechnologie Spec: ISO/IEC/IEEE 26514, §8 .
Structuur wordt niet geïmproviseerd. Onderwerpen worden georganiseerd in een bevroren hiërarchie met metadata (sectie, doelgroep, bewijsniveau), zodat een lezer een pagina op herkenning kan vinden Spec: ISO/IEC/IEEE 26514, §9 , en de belangrijkste uitspraak staat bovenaan elke pagina Spec: ISO 24495-1, §5 .
De toon wordt bepaald door een bekrachtigde stijlhiërarchie — Apple voor tone of voice, Microsoft voor procedures, Google voor code, eenvoudige taal als basis — vastgelegd in de repository met de upstream-clausule die elke afwijking overschrijft.
Kwaliteit wordt machinaal gecontroleerd. Vale handhaaft de voice packs; een reeks composer docs:*-poorten bewaakt de integriteit van links, citaathygiëne, het vermijden van letterlijke normtekst en het voorkomen van lekken van vertrouwelijke details.
Documentatie wordt samen met de code, iteratief ontwikkeld — elke wijziging levert haar documentatie mee, niet pas achteraf als achterstallig werk Spec: ISO/IEC/IEEE 26515, §Introduction .

Hoe NextPDF dit aanpakt

Een kwaliteitsmodel, vastgelegd op papier

„Goede documentatie” is niet falsifieerbaar totdat je de kenmerken benoemt. NextPDF herformuleert de §8-criteria voor gebruikersinformatie in eigen bewoordingen als de lat waaraan elke Insider_-pagina wordt afgemeten: elke pagina moet technisch correct zijn, vasthouden aan één consistente woordenschat, begrijpelijk zijn voor de aangewezen lezer, alleen bevatten wat die lezer nodig heeft en toch niets noodzakelijks weglaten, en bereikbaar blijven voor hulptechnologie Spec: ISO/IEC/IEEE 26514, §8 . Dat zijn geen bijvoeglijke naamwoorden; het zijn beoordelingscriteria. De toets „nodig maar volledig” is de reden waarom een pagina haar grens vermeldt en stopt, in plaats van op te vullen. Consistentie van de woordenschat is de reden waarom de terminologie wordt beheerd (hieronder). Bereikbaarheid is de reden waarom elke component veilig is voor toetsenbord en schermlezer, en nooit alleen via kleur signaleert.

Structuur op basis van analyse, niet van smaak

De Insider_-taxonomie wordt bevroren voordat ook maar één pagina is geschreven. Dat is bewust gedaan. ISO 26514 vereist dat de analyse van doelgroep en taken voorafgaat aan het ontwerpen van de informatie Spec: ISO/IEC/IEEE 26514, §9 . Het vereist ook dat onderwerpen worden georganiseerd in hiërarchieën of groepen, elk voorzien van metadata die de doelgroep en het informatietype aanduidt, zodat gebruikers snel vinden wat ze nodig hebben Spec: ISO/IEC/IEEE 26514, §9 . In deze repository is die metadata concrete front-matter — section, audience, evidence_level, tags — en de clusterkaart is één enkel bevroren bestand. Een lezer kiest een pagina op basis van herkenning; niemand hoeft een slug te onthouden.

Binnen een pagina is de volgorde vast en overal hetzelfde, en de nuttigste uitspraak staat waar een lezer die als eerste zal vinden — meestal aan het begin Spec: ISO 24495-1, §5 . Daarom zet elke Insider_-pagina De korte versie vóór de details: een lezer kan na drie secties stoppen en toch met een verdedigbaar antwoord vertrekken.

Een stijlhiërarchie met bewijsstukken

De toon wordt niet overgelaten aan de stemming van de schrijver. De repository bevat een bekrachtigd overridebestand (docs/style/nextpdf-overrides.md) dat Apple (toon), Microsoft MSTP (procedures en UI-termen) en Google DDSG (code en CLI) combineert met basislijnen voor eenvoudige taal en gecontroleerde woordenschat, met een conflictoplossingstabel per modus. De strengste regel overschrijft ze allemaal: geen letterlijke tekst uit een gelicentieerde normalisatie-instelling. Elk punt waar NextPDF afwijkt van een upstream-stijlgids wordt vastgelegd met de upstream-clausule die het overschrijft en de reden. Het stijlblad citeert zijn eigen bronnen op dezelfde manier als een pagina dat doet.

Kwaliteit die je niet op goed vertrouwen hoeft aan te nemen

De discipline wordt afgedwongen door tooling, niet door goede bedoelingen:

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.

De kwaliteitspoorten voor documentatie, in de volgorde waarin een pagina ze doorloopt: een ingevuld scaffold legt de structuur vast; Vale handhaaft de voice packs; de docs:*-poorten handhaven de integriteit van koppelingen, citaathygiëne, geen letterlijke normtekst en geen lekken van vertrouwelijke informatie; de review bevestigt de bewijsbasis. Een pagina die een poort niet doorstaat, is een defect, behandeld als een falende test.

Deze stappen verwijzen naar echte entries in de composer.json van deze repository. docs:lint draait de NDA- en linkpoorten lokaal. docs:jaccard-fingerprint markeert hergebruik van letterlijke normtekst boven een overeenkomstsdrempel. docs:rag-fallback-check is een volledig geïmplementeerde, offline en deterministische handhaver van het protocol voor citaatintegriteit. De live RAG-herverificatie (docs:rag-citation-check) en sommige scanners zijn als poorten aangesloten, terwijl hun diepere runners nog worden uitgebouwd. De eerlijke formulering is deze: het contract is bekrachtigd en de structurele controles worden vandaag afgedwongen; de campagne om elke controle exhaustief te maken loopt nog. Insider_ claimt geen groen dashboard dat het niet heeft verdiend — en past daarmee zelf het criterium “correct” uit het kwaliteitsmodel op deze pagina toe.

Wat het bewijs zegt

Deze pagina is Evidence: Standard-backed voor de claims over documentatiekwaliteit en grounded in-repo voor de claims over handhaving. Die dubbele basis is bewust gekozen: de principes komen uit normen; de handhaving is verifieerbaar door de repository te lezen.

Claim	Basis	Anker
Docs hebben een gedefinieerde kwaliteitslat	Norm	Correct, één woordenschat, begrijpelijk voor de lezer, nodig maar volledig, bereikbaar voor hulptechnologie Spec: ISO/IEC/IEEE 26514, §8
Terminologie wordt beheerd	Norm	Consistente terminologie in de hele informatieset Spec: ISO/IEC/IEEE 26514, §8
Structuur gaat vooraf aan schrijven	Norm	Doelgroep- en taakanalyse vóór ontwerp Spec: ISO/IEC/IEEE 26514, §9
De nuttigste uitspraak komt eerst	Norm	Belangrijkste boodschap aan het begin Spec: ISO 24495-1, §5
Docs worden samen met de code geleverd	Norm	De deliverables van elke iteratie bevatten gebruikersinformatie Spec: ISO/IEC/IEEE 26515, §Introduction
Kwaliteit wordt machinaal gecontroleerd	In de repository	`composer.jsondocs:*`-poorten; het bekrachtigde `docs/style/nextpdf-overrides.md`; de actieve Vale-configuratie

Praktisch voorbeeld

De discipline wordt zichtbaar op de kleinste schaal: een kwaliteitsgegeven wordt nooit met de hand in de tekst getypt, omdat een getal in lopende tekst ongemerkt kan verouderen. Het wordt weergegeven door een component die weigert een waarde te verzinnen en wordt onderbouwd door de bewijsbasis van de pagina:

<?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');

Het draait om de throw. Het criterium „correct” van het informatiekwaliteitsmodel is hier niet vrijblijvend; de structuur dwingt het af, zodat een verouderd cijfer niet ongemerkt kan worden meegeleverd.

Veelvoorkomend misverstand

De valkuil is om „documentatie als product” te lezen als een slogan over afwerking — mooiere tekst, fraaiere pagina’s. Het is het tegenovergestelde van cosmetisch. Het betekent dat de documentatie een gedefinieerde kwaliteitslat, een beheerde woordenschat, een bevroren structuur en machinaal gecontroleerde poorten heeft. Een pagina die een van die poorten niet doorstaat, is een defect met een oplossing, behandeld als een falende test. Afwerking is een bijproduct van de discipline, niet het doel ervan.

De tweede valkuil is de aanname dat elke poort al volledig is omdat het contract bestaat. Dat is niet zo, en deze pagina zegt dat onomwonden. De structurele controles worden vandaag afgedwongen; de diepere verificatietools worden uitgebouwd. Iets anders beweren zou juist het kwaliteitsmodel schenden dat deze pagina beschrijft.

Beperkingen en grenzen

Deze pagina beschrijft de documentatiediscipline. Ze is niet het stijlblad, het taxonomiebestand of de poortimplementaties zelf. Ze doet geen uitspraken over enginegedrag. De gezaghebbende artefacten staan in de repository (docs/style/nextpdf-overrides.md, de bevroren taxonomie, de composer.json-docs:*-scripts) en hebben voorrang op elke samenvatting hier als ze daarvan afwijken.

Het handhavingsoppervlak is, eerlijk toegegeven, gedeeltelijk. De fallbackcontrole voor citaatintegriteit is actief. De koppelings- en NDA-poorten draaien lokaal. De verificatietools voor letterlijke citaten en live citaten zijn aangesloten, terwijl hun volledige runners nog worden uitgebouwd. Dit wordt gerapporteerd als in uitvoering, niet als voltooid. Waar deze pagina raakt aan documentatie van het Premium-niveau, geldt de beschreven discipline op procesniveau, nooit op het niveau van een niet-openbaar mechanisme.

Gerelateerde documentatie

Citaatdiscipline — de strengste regel in de stijlhiërarchie en het systeem van bewijsniveaus waarop deze pagina steunt.
Het normenlandschap — de normen die deze discipline citeert en hoe een clausule gedocumenteerd gedrag wordt.
De ontwerpfilosofie van NextPDF — de engineeringvisie die een documentatiedefect behandelt als een codedefect.

Verklarende woordenlijst

Informatiekwaliteitsmodel — de herformulering door NextPDF van de §8-criteria voor gebruikersinformatie uit ISO 26514 (correct, één woordenschat, begrijpelijk voor de lezer, nodig maar volledig, bereikbaar voor hulptechnologie), gebruikt als beoordelingslat voor elke Insider_-pagina.
Eenvoudige taal — communicatie waarvan de bewoording, structuur en vormgeving de beoogde lezers in staat stellen de inhoud te vinden, te begrijpen en te gebruiken; een basislijn die in alle modi wordt toegepast, geen inhoudstype.
Stijlhiërarchie — de bekrachtigde, gelaagde reeks upstream-stijlgidsen (Apple, Microsoft, Google, plus basislijnen voor eenvoudige taal en gecontroleerde woordenschat), waarbij elke afwijking van NextPDF tegenover de bron wordt vastgelegd.
Kwaliteitspoort — een geautomatiseerde controle (een Vale-pack of een composer docs:*-script) die een pagina moet doorstaan; een fout is een documentatiedefect, geen muggenzifterij.
Front-mattermetadata — de machineleesbare header (section, audience, evidence_level, tags) die een pagina vindbaar en classificeerbaar maakt, volgens de eis voor onderwerporganisatie.