Documentation as a product

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

At a glance

These pages are built to a documentation-quality model, written under a plain- language baseline and a layered style hierarchy, and checked by the same kind of automated gates that run on the engine’s code. This page explains that discipline and why NextPDF logs a documentation defect as an engineering defect.

It is written for a senior engineer who has been burned by confident, unverifiable docs and wants to know what makes these different before trusting them.

Why this matters

A document library is bought on trust, and the documentation is where that trust is granted or withdrawn. A page that is wrong in a way you cannot detect is worse than no page at all. It converts your caution into misplaced confidence. The failure surfaces in production with your name on the commit.

The standards literature is blunt about the stakes. Well-designed user information does more than reduce support cost; it enhances the reputation of the product and its producer. You earn that by putting verification and validation testing inside development, not after it Spec: ISO/IEC/IEEE 26513, §Foreword . NextPDF takes that literally: documentation is a product surface with a quality bar, not a courtesy attached to the code.

The short version

NextPDF holds these docs to an explicit information-quality model derived from the §8 user-information criteria: a page must be technically accurate, use one consistent vocabulary, be understandable by its stated reader, say only what is needed yet omit nothing required, and remain reachable to assistive technology Spec: ISO/IEC/IEEE 26514, §8 .
Structure is not improvised. Topics are organised into a frozen hierarchy with metadata (section, audience, evidence level) so a reader can find one by recognition Spec: ISO/IEC/IEEE 26514, §9 , and the most important statement sits near the top of each page Spec: ISO 24495-1, §5 .
Voice is governed by a ratified style hierarchy — Apple for tone, Microsoft for procedure, Google for code, plain language across all of it — recorded in-repo with the upstream clause every divergence overrides.
Quality is machine-checked. Vale enforces the voice packs; a set of composer docs:* gates enforce link integrity, citation hygiene, no verbatim standards text, and no leakage of private detail.
Docs are developed with the code, iteratively — each change ships its documentation, not a backlog of it Spec: ISO/IEC/IEEE 26515, §Introduction .

How NextPDF approaches it

A quality model, written down

“Good docs” is unfalsifiable until you name the attributes. NextPDF restates the §8 user-information criteria in its own terms as the bar every Insider_ page is measured against: each page must be technically accurate, hold to one consistent vocabulary, be understandable to its stated reader, carry only what that reader needs while omitting nothing required, and stay reachable to assistive technology Spec: ISO/IEC/IEEE 26514, §8 . Those are not adjectives; they are review criteria. The “needed but complete” test is why a page states its boundary and stops, rather than padding. Vocabulary consistency is why terminology is governed (below). Reachability is why every component is keyboard- and screen-reader-safe and never signals by colour alone.

Structure by analysis, not by taste

The Insider_ taxonomy is frozen before any page is written. That is deliberate. ISO 26514 requires that audience and task analysis precedes designing the information Spec: ISO/IEC/IEEE 26514, §9 . It also requires that topics be organised into hierarchies or groups, each carrying metadata that identifies its audience and information type, so users locate what they need quickly Spec: ISO/IEC/IEEE 26514, §9 . In this repository that metadata is concrete front-matter — section, audience, evidence_level, tags — and the cluster map is a single frozen file. A reader selects a page by recognition; no one has to recall a slug.

Within a page, the order is fixed and the same everywhere, and the most useful statement is placed where a reader will find it first — commonly the beginning Spec: ISO 24495-1, §5 . That is why every Insider_ page puts The short version before the detail: a reader can stop after three sections and still leave with a defensible answer.

A style hierarchy with receipts

Voice is not left to the writer’s mood. The repository carries a ratified override sheet (docs/style/nextpdf-overrides.md) that layers Apple (tone), Microsoft MSTP (procedure and UI terms), and Google DDSG (code and CLI) over plain-language and controlled-vocabulary baselines, with a per-mode conflict-resolution table. Its strictest rule overrides all of them: no verbatim text from a licensed standards body. Every point where NextPDF diverges from an upstream guide is recorded with the upstream clause it overrides and the reason. The style sheet cites its own sources the same way a page does.

Quality you do not have to take on faith

The discipline is enforced by tooling, not by good 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.

The documentation quality gates, in the order a page passes them: a populated scaffold fixes the structure; Vale enforces the voice packs; the docs:* gates enforce link integrity, citation hygiene, no verbatim standards text, and no private leakage; review confirms the evidence basis. A page that fails a gate is a defect, treated like a failing test.

These map to real entries in this repository’s composer.json. docs:lint runs the NDA and link gates locally. docs:jaccard-fingerprint flags verbatim standards-text reuse above a similarity threshold. docs:rag-fallback-check is a fully-implemented, offline, deterministic enforcer of the citation-integrity protocol. The live RAG re-verification (docs:rag-citation-check) and some scanners are wired as gates, with their deeper runners still being built out. The honest statement is this: the contract is ratified and the structural checks are enforced today; the campaign to make every check exhaustive is ongoing. Insider_ does not claim a green dashboard it has not earned — which is itself the quality model’s “correct” criterion applied to this page.

What the evidence says

This page is Evidence: Standard-backed for the documentation- quality claims and grounded in-repo for the enforcement claims. The dual basis is deliberate: the principles come from standards; the enforcement is verifiable by reading the repository.

Claim	Basis	Anchor
Docs have a defined quality bar	Standard	Accurate, single-vocabulary, reader-understandable, needed-but-complete, assistive-tech-reachable Spec: ISO/IEC/IEEE 26514, §8
Terminology is governed	Standard	Consistent terminology across the information set Spec: ISO/IEC/IEEE 26514, §8
Structure precedes writing	Standard	Audience and task analysis before design Spec: ISO/IEC/IEEE 26514, §9
Most useful statement comes first	Standard	Most important message at the beginning Spec: ISO 24495-1, §5
Docs ship with the code	Standard	Each iteration’s deliverables include user information Spec: ISO/IEC/IEEE 26515, §Introduction
Quality is machine-checked	In-repo	`composer.jsondocs:*` gates; the ratified `docs/style/nextpdf-overrides.md`; the active Vale config

Practical example

The discipline shows up at the smallest scale: a quality datum is never hand-typed into prose, because a number in prose silently goes stale. It is rendered by a component that refuses to invent a value and is backed by the page’s evidence basis:

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

The point is the throw. The information-quality model’s “correct” criterion is not advisory here; the structure enforces it so a stale figure cannot quietly ship.

Common misconception

The trap is reading “documentation as a product” as a slogan about polish — nicer prose, prettier pages. It is the opposite of cosmetic. It means the docs carry a defined quality bar, a governed vocabulary, a frozen structure, and machine-checked gates. A page that fails any of them is a defect with a fix, handled like a failing test. Polish is a by-product of the discipline, not its purpose.

The second trap is assuming every gate is already exhaustive because the contract exists. It is not, and this page says so plainly. The structural checks are enforced today; the deeper verifiers are being built out. Claiming otherwise would violate the very quality model this page describes.

Limits and boundaries

This page describes the documentation discipline. It is not the style sheet, the taxonomy file, or the gate implementations themselves. It asserts no engine behaviour. The authoritative artefacts are in-repo (docs/style/nextpdf-overrides.md, the frozen taxonomy, the composer.json docs:* scripts) and supersede any summary here if they diverge.

The enforcement surface is partial by honest admission. The citation-integrity fallback check is live. The link and NDA gates run locally. The verbatim-quote and live-citation verifiers are wired with their exhaustive runners still landing. This is reported as in-progress, not as done. Where this page touches Premium-tier documentation, the discipline described applies at the level of process, never at the level of any non-public mechanism.

Citation discipline — the strictest rule in the style hierarchy, and the evidence-level system this page relies on.
The standards landscape — the standards this discipline cites, and how a clause becomes documented behaviour.
The NextPDF design philosophy — the engineering taste that treats a documentation defect like a code defect.

Glossary

Information-quality model — NextPDF’s restatement of the ISO 26514 §8 user-information criteria (accurate, single-vocabulary, reader-understandable, needed-but-complete, assistive-tech-reachable) used as the review bar for every Insider_ page.
Plain language — communication whose wording, structure, and design let intended readers find, understand, and use the content; a baseline applied across modes, not a content type.
Style hierarchy — the ratified, layered set of upstream style guides (Apple, Microsoft, Google, plus plain-language and controlled-vocabulary baselines) with every NextPDF divergence recorded against its source.
Quality gate — an automated check (a Vale pack or a composer docs:* script) a page must pass; a failure is a documentation defect, not a nit.
Front-matter metadata — the machine-readable header (section, audience, evidence_level, tags) that makes a page locatable and classifiable, per the topic-organisation requirement.