Dokumentation als Produkt

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

Auf einen Blick

Diese Seiten sind nach einem Dokumentationsqualitätsmodell aufgebaut, auf Grundlage klarer Sprache und einer mehrschichtigen Stilhierarchie verfasst und durch dieselbe Art automatisierter Gates geprüft, die auch für den Engine-Code laufen. Diese Seite erläutert diese Disziplin und warum ein Dokumentationsfehler als Engineering-Fehler erfasst wird.

Sie richtet sich an erfahrene Entwicklerinnen und Entwickler, die bereits schlechte Erfahrungen mit selbstsicherer, nicht überprüfbarer Dokumentation gemacht haben und wissen wollen, was diese Dokumentation anders macht, bevor sie ihr vertrauen.

Warum das wichtig ist

Eine Dokumentbibliothek kauft man auf Vertrauensbasis, und in der Dokumentation entsteht oder zerbricht dieses Vertrauen. Eine Seite, die auf eine für Sie nicht erkennbare Weise falsch ist, ist schlimmer als gar keine Seite. Sie verwandelt Ihre Vorsicht in fehlgeleitetes Vertrauen. Der Fehler tritt in der Produktion zutage, mit Ihrem Namen im Commit.

Die Normenliteratur macht deutlich, was auf dem Spiel steht. Gut gestaltete Benutzerinformationen senken nicht nur die Supportkosten — sie stärken den Ruf des Produkts und seines Herstellers. Dieses Vertrauen entsteht, wenn Verifikations- und Validierungstests Teil der Entwicklung sind, statt erst danach nachgereicht zu werden Spec: ISO/IEC/IEEE 26513, §Foreword . NextPDF nimmt das wörtlich: Dokumentation ist eine Produktoberfläche mit einem Qualitätsmaßstab, keine höfliche Beigabe zum Code.

Die Kurzfassung

NextPDF misst diese Dokumentation an einem expliziten Informationsqualitätsmodell, abgeleitet aus den Benutzerinformations-Kriterien aus §8: Eine Seite muss technisch korrekt sein, ein einziges konsistentes Vokabular verwenden, für die genannte Leserschaft verständlich sein, nur das Nötige sagen, dabei nichts Erforderliches auslassen und für assistive Technologien zugänglich bleiben Spec: ISO/IEC/IEEE 26514, §8 .
Die Struktur wird nicht improvisiert. Themen werden in einer festgeschriebenen Hierarchie mit Metadaten organisiert (Abschnitt, Zielgruppe, Belegstufe), damit eine Leserin oder ein Leser ein Thema durch Wiedererkennung findet Spec: ISO/IEC/IEEE 26514, §9 , und die wichtigste Aussage steht nahe am Anfang jeder Seite Spec: ISO 24495-1, §5 .
Der Ton wird durch eine ratifizierte Stilhierarchie geregelt — Apple für den Ton, Microsoft für Abläufe, Google für Code, klare Sprache als übergreifende Basis — im Repository festgehalten, samt der vorgelagerten Klausel, die durch jede Abweichung außer Kraft gesetzt wird.
Qualität wird maschinell geprüft. Vale erzwingt die Voice-Packs; eine Reihe von composer docs:*-Gates erzwingt Link-Integrität, Zitierhygiene, keinen wörtlichen Normentext und keine Offenlegung privater Details.
Die Dokumentation wird gemeinsam mit dem Code, iterativ entwickelt — jede Änderung liefert ihre Dokumentation mit, nicht erst einen Nachtrag dazu Spec: ISO/IEC/IEEE 26515, §Introduction .

Wie NextPDF dabei vorgeht

Ein Qualitätsmodell, schriftlich festgehalten

“Gute Dokumentation” ist nicht überprüfbar, solange Sie ihre Eigenschaften nicht benennen. NextPDF formuliert die Benutzerinformations-Kriterien aus §8 in eigenen Worten als Prüfmaßstab neu, an dem jede Insider_-Seite gemessen wird: Jede Seite muss technisch korrekt sein, an einem einzigen konsistenten Vokabular festhalten, für die anvisierte Leserschaft verständlich sein, nur das enthalten, was diese Leserschaft braucht, dabei nichts Erforderliches auslassen und für assistive Technologien zugänglich bleiben Spec: ISO/IEC/IEEE 26514, §8 . Das sind keine Adjektive; es sind Prüfkriterien. Der Test “nötig, aber vollständig” ist der Grund, warum eine Seite ihre Grenze nennt und dann aufhört, statt sie aufzublähen. Vokabularkonsistenz ist der Grund, warum die Terminologie geregelt ist (siehe unten). Zugänglichkeit ist der Grund, warum jede Komponente per Tastatur bedienbar und für Screenreader nutzbar ist und niemals allein über Farbe signalisiert.

Struktur durch Analyse, nicht durch Geschmack

Die Insider_-Taxonomie wird eingefroren, bevor eine einzige Seite geschrieben wird. Das ist Absicht. ISO 26514 verlangt, dass die Zielgruppen- und Aufgabenanalyse dem Entwurf der Information vorausgeht Spec: ISO/IEC/IEEE 26514, §9 . Sie verlangt außerdem, dass Themen in Hierarchien oder Gruppen organisiert werden, die jeweils Metadaten tragen, welche Zielgruppe und Informationstyp benennen, damit Benutzer schnell finden, was sie brauchen Spec: ISO/IEC/IEEE 26514, §9 . In diesem Repository sind diese Metadaten konkret in der Front-Matter abgebildet — section, audience, evidence_level, tags — und die Cluster-Karte ist eine einzige eingefrorene Datei. Eine Leserin oder ein Leser wählt eine Seite durch Wiedererkennung; niemand muss sich je einen Slug merken.

Innerhalb einer Seite ist die Reihenfolge fest und durchgängig gleich, und die nützlichste Aussage steht dort, wo eine Leserin oder ein Leser sie zuerst findet — meist am Anfang Spec: ISO 24495-1, §5 . Deshalb stellt jede Insider_-Seite Die Kurzfassung vor das Detail: Eine Leserin oder ein Leser kann nach drei Abschnitten aufhören und trotzdem mit einer belastbaren Antwort weiterarbeiten.

Eine Stilhierarchie mit Belegen

Der Tonfall bleibt nicht der Laune der Verfasserin oder des Verfassers überlassen. Das Repository führt ein ratifiziertes Override-Blatt (docs/style/nextpdf-overrides.md), das Apple (Ton), Microsoft MSTP (Abläufe und UI-Begriffe) und Google DDSG (Code und CLI) über die Basislinien für klare Sprache und kontrolliertes Vokabular legt, samt einer Konfliktlösungstabelle pro Modus. Seine strengste Regel setzt alle anderen außer Kraft: keine wörtliche Übernahme von Text einer lizenzierten Normungsorganisation. Entscheidend ist, dass jede Stelle, an der NextPDF von einem vorgelagerten Leitfaden abweicht, mit der vorgelagerten Klausel, die NextPDF dabei außer Kraft setzt, und mit dem Grund festgehalten wird. Das Stilblatt zitiert seine eigenen Quellen auf dieselbe Weise wie eine Seite.

Qualität, die Sie nicht auf Treu und Glauben hinnehmen müssen

Die Disziplin wird durch Werkzeuge erzwungen, nicht durch guten Willen:

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.

Die Qualitäts-Gates der Dokumentation, in der Reihenfolge, in der eine Seite sie durchläuft: Ein befülltes Scaffold setzt die Struktur; Vale erzwingt die Voice-Packs; die docs:*-Gates erzwingen Link-Integrität, Zitierhygiene, keinen wörtlichen Normentext und kein Durchsickern privater Details; die Review bestätigt die Belegbasis. Eine Seite, die ein Gate nicht besteht, ist ein Fehler und wird wie ein fehlgeschlagener Test behandelt.

Diese Gates entsprechen realen Einträgen in der composer.json dieses Repositorys. docs:lint führt die NDA- und Link-Gates lokal aus. docs:jaccard-fingerprint markiert die wörtliche Wiederverwendung von Normentext oberhalb eines Ähnlichkeitsschwellenwerts. docs:rag-fallback-check ist ein vollständig implementierter, offline lauffähiger und deterministischer Durchsetzer des Protokolls zur Zitatintegrität. Die Live-RAG-Revalidierung (docs:rag-citation-check) und einige Scanner sind als Gates verdrahtet; ihre tiefer gehenden Runner werden noch ausgebaut. Die ehrliche Aussage lautet: Der Vertrag ist ratifiziert und die strukturellen Prüfungen werden heute erzwungen; die Kampagne, jede Prüfung erschöpfend zu machen, läuft weiter. Insider_ behauptet kein grünes Dashboard, das es sich nicht verdient hat — das ist das Kriterium “korrekt” des Qualitätsmodells, angewandt auf diese Seite.

What the evidence says

Diese Seite ist für Aussagen zur Dokumentationsqualität Evidence: Standard-backed und für Aussagen zur Durchsetzung im Repository verankert. Diese doppelte Grundlage ist Absicht: Die Prinzipien stammen aus Normen; die Durchsetzung lässt sich durch Lektüre des Repositorys prüfen.

Aussage	Grundlage	Anker
Die Dokumentation hat einen definierten Qualitätsmaßstab	Standard	Korrekt, einheitliches Vokabular, für die Leserschaft verständlich, nötig-aber-vollständig, für assistive Technologien zugänglich Spec: ISO/IEC/IEEE 26514, §8
Terminologie ist geregelt	Standard	Einheitliche Terminologie über den gesamten Informationssatz hinweg Spec: ISO/IEC/IEEE 26514, §8
Struktur geht dem Schreiben voraus	Standard	Zielgruppen- und Aufgabenanalyse vor dem Entwurf Spec: ISO/IEC/IEEE 26514, §9
Die nützlichste Aussage steht zuerst	Standard	Wichtigste Aussage am Anfang Spec: ISO 24495-1, §5
Dokumentation wird mit dem Code ausgeliefert	Standard	Jede Iteration liefert Benutzerinformationen mit Spec: ISO/IEC/IEEE 26515, §Introduction
Qualität wird maschinell geprüft	Im Repository	`composer.jsondocs:*`-Gates; das ratifizierte `docs/style/nextpdf-overrides.md`; die aktive Vale-Konfiguration

Praktisches Beispiel

Die Disziplin zeigt sich im kleinsten Maßstab — ein Qualitätsdatum wird nie händisch in den Fließtext geschrieben, weil eine Zahl im Fließtext unbemerkt veralten kann. Es wird von einer Komponente gerendert, die sich weigert, einen Wert zu erfinden, und durch die Belegbasis der Seite gestützt wird:

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

Worauf es ankommt, ist das throw. Das Kriterium “korrekt” des Informationsqualitätsmodells ist hier nicht nur eine Empfehlung; es wird strukturell erzwungen, damit eine veraltete Zahl nicht stillschweigend ausgeliefert werden kann.

Häufiges Missverständnis

Die Falle besteht darin, “Dokumentation als Produkt” als Schlagwort für Politur zu lesen — schönerer Text, hübschere Seiten. Es ist das Gegenteil von Kosmetik. Es bedeutet, dass die Dokumentation einen definierten Qualitätsmaßstab, ein geregeltes Vokabular, eine eingefrorene Struktur und maschinell geprüfte Gates hat und dass eine Seite, die eines davon nicht besteht, ein Fehler ist, der behoben werden muss und wie ein fehlgeschlagener Test behandelt wird. Politur ist ein Nebenprodukt der Disziplin, nicht ihr Zweck.

Die zweite Falle besteht darin, anzunehmen, jedes Gate sei bereits erschöpfend, nur weil der Vertrag existiert. Das ist es nicht, und diese Seite sagt das unumwunden. Die strukturellen Prüfungen werden heute erzwungen; die tiefer gehenden Verifizierer werden noch ausgebaut. Etwas anderes zu behaupten würde genau das Qualitätsmodell verletzen, das diese Seite beschreibt.

Grenzen und Abgrenzungen

Diese Seite beschreibt die Disziplin der Dokumentation. Sie ist nicht das Stilblatt, die Taxonomiedatei oder die Gate-Implementierungen selbst. Sie behauptet kein Verhalten der Engine. Die maßgeblichen Artefakte liegen im Repository (docs/style/nextpdf-overrides.md, die eingefrorene Taxonomie, die composer.json-docs:*-Skripte) und haben Vorrang vor jeder Zusammenfassung hier, falls sie voneinander abweichen.

Der Durchsetzungsumfang ist ehrlicherweise nur teilweise vorhanden. Die Fallback-Prüfung zur Zitatintegrität ist aktiv. Die Link- und NDA-Gates laufen lokal. Die Verifizierer für wörtliche Zitate und Live-Zitate sind verdrahtet, ihre erschöpfenden Runner werden noch nachgeliefert. Das wird als laufende Arbeit ausgewiesen, nicht als abgeschlossen. Wo diese Seite Premium-Tier-Dokumentation berührt, gilt die beschriebene Disziplin auf der Ebene des Prozesses, niemals auf der Ebene irgendeines nicht-öffentlichen Mechanismus.

Glossar

Informationsqualitätsmodell — die Neuformulierung der Benutzerinformations-Kriterien aus ISO 26514 §8 durch NextPDF (korrekt, einheitliches Vokabular, für die Leserschaft verständlich, nötig-aber-vollständig, für assistive Technologien zugänglich), die als Prüfmaßstab für jede Insider_-Seite dient.
Klare Sprache — Kommunikation, deren Wortwahl, Struktur und Gestaltung es der vorgesehenen Leserschaft ermöglichen, den Inhalt zu finden, zu verstehen und zu nutzen; eine Basislinie, die über alle Modi hinweg angewandt wird, kein Inhaltstyp.
Stilhierarchie — der ratifizierte, mehrschichtige Satz vorgelagerter Stilleitfäden (Apple, Microsoft, Google, dazu die Basislinien für klare Sprache und kontrolliertes Vokabular), in dem jede NextPDF-Abweichung von einem vorgelagerten Leitfaden mit Bezug auf ihre Quelle festgehalten ist.
Qualitäts-Gate — eine automatisierte Prüfung (ein Vale-Pack oder ein composer docs:*-Skript), die eine Seite bestehen muss; ein Fehlschlag ist ein Dokumentationsfehler, keine Kleinigkeit.
Front-Matter-Metadaten — der maschinenlesbare Header (section, audience, evidence_level, tags), der eine Seite auffindbar und klassifizierbar macht, gemäß der Anforderung zur Themenorganisation.