Dokumentacja jako produkt

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

W skrócie

Te strony są tworzone według modelu jakości dokumentacji, pisane zgodnie z zasadami prostego języka i warstwową hierarchią stylów oraz weryfikowane przez ten sam rodzaj automatycznych bramek, które sprawdzają kod silnika. Ta strona wyjaśnia tę dyscyplinę i pokazuje, dlaczego NextPDF rejestruje defekt dokumentacji jako defekt inżynieryjny.

Jest przeznaczona dla doświadczonego inżyniera, który zetknął się już z dokumentacją brzmiącą pewnie, lecz niemożliwą do zweryfikowania, i chce wiedzieć, co odróżnia tę dokumentację, zanim zacznie jej ufać.

Dlaczego to ma znaczenie

Bibliotekę do obsługi dokumentów wybiera się ze względu na zaufanie, a to właśnie dokumentacja decyduje o tym, czy zaufanie powstaje, czy znika. Strona zawierająca niewykrywalny błąd jest gorsza niż brak strony w ogóle. Zastępuje ostrożność nieuzasadnioną pewnością. Awaria ujawnia się na produkcji, przy commicie podpisanym twoim nazwiskiem.

Normy mówią o stawce bez ogródek. Dobrze zaprojektowane informacje dla użytkownika robią coś więcej niż obniżają koszty wsparcia: wzmacniają reputację produktu i jego producenta. Taki efekt osiąga się przez włączenie testów weryfikacyjnych i walidacyjnych do procesu wytwarzania, a nie po nim Spec: ISO/IEC/IEEE 26513, §Foreword . NextPDF traktuje to dosłownie: dokumentacja jest powierzchnią produktu z poprzeczką jakości, a nie grzecznościowym dodatkiem do kodu.

Wersja skrócona

NextPDF rozlicza tę dokumentację z jawnego modelu jakości informacji wywiedzionego z kryteriów informacji dla użytkownika z §8: strona musi być technicznie poprawna, posługiwać się jednym spójnym słownictwem, być zrozumiała dla wskazanego czytelnika, przekazywać tylko potrzebne informacje, a zarazem nie pomijać niczego wymaganego oraz pozostawać dostępna dla technologii wspomagających Spec: ISO/IEC/IEEE 26514, §8 .
Struktura nie jest improwizowana. Tematy są uporządkowane w zamrożoną hierarchię z metadanymi (sekcja, odbiorca, poziom dowodów), aby czytelnik mógł odnaleźć temat przez rozpoznanie Spec: ISO/IEC/IEEE 26514, §9 , a najważniejsze stwierdzenie znajduje się na początku każdej strony Spec: ISO 24495-1, §5 .
Stylem wypowiedzi rządzi zatwierdzona hierarchia stylów — Apple dla tonu, Microsoft dla procedur, Google dla kodu, prosty język dla całości — zapisana w repozytorium wraz z nadrzędną klauzulą, którą każde odstępstwo zastępuje.
Jakość jest weryfikowana maszynowo. Vale egzekwuje pakiety stylu; zestaw bramek composer docs:* egzekwuje integralność odnośników, higienę cytowań, brak dosłownego tekstu norm oraz brak wycieku poufnych szczegółów.
Dokumentacja jest tworzona wraz z kodem, iteracyjnie — każda zmiana dostarcza odpowiadającą jej dokumentację, a nie odkłada jej na zaległości Spec: ISO/IEC/IEEE 26515, §Introduction .

Jak podchodzi do tego NextPDF

Model jakości zapisany wprost

„Dobra dokumentacja” jest niefalsyfikowalna, dopóki nie nazwie się jej cech. NextPDF przekłada kryteria informacji dla użytkownika z §8 na własne brzmienie i używa ich jako poprzeczki, względem której mierzona jest każda strona Insider_: każda strona musi być technicznie poprawna, trzymać się jednego spójnego słownictwa, być zrozumiała dla wskazanego czytelnika, zawierać tylko to, czego ten czytelnik potrzebuje, nie pomijając niczego wymaganego, oraz pozostawać dostępna dla technologii wspomagających Spec: ISO/IEC/IEEE 26514, §8 . To nie są przymiotniki; to kryteria recenzji. Test „potrzebne, lecz kompletne” jest powodem, dla którego strona określa swoją granicę i kończy się, zamiast wypełniać treść balastem. Spójność słownictwa jest powodem, dla którego terminologia jest objęta nadzorem (poniżej). Dostępność jest powodem, dla którego każdy komponent jest obsługiwalny z klawiatury i czytnika ekranu oraz nigdy nie sygnalizuje wyłącznie kolorem.

Struktura z analizy, nie z gustu

Taksonomia Insider_ jest zamrażana, zanim powstanie jakakolwiek strona. To celowy zabieg. ISO 26514 wymaga, aby analiza odbiorców i zadań poprzedzała projektowanie informacji Spec: ISO/IEC/IEEE 26514, §9 . Wymaga również, aby tematy były uporządkowane w hierarchie lub grupy, z których każda zawiera metadane wskazujące odbiorcę i typ informacji, tak aby użytkownicy szybko odnajdywali to, czego potrzebują Spec: ISO/IEC/IEEE 26514, §9 . W tym repozytorium tymi metadanymi jest konkretny front-matter — section, audience, evidence_level, tags — a mapa klastrów to pojedynczy zamrożony plik. Czytelnik wybiera stronę przez rozpoznanie; nie musi odtwarzać z pamięci sluga.

W obrębie strony kolejność jest stała i wszędzie taka sama, a najbardziej przydatne stwierdzenie umieszcza się tam, gdzie czytelnik znajdzie je jako pierwsze — zwykle na początku Spec: ISO 24495-1, §5 . Dlatego każda strona Insider_ umieszcza Wersję skróconą przed szczegółami: czytelnik może zatrzymać się po trzech sekcjach i wciąż wyjść z możliwą do obrony odpowiedzią.

Hierarchia stylów z dowodami

Styl wypowiedzi nie zależy od nastroju autora. Repozytorium zawiera zatwierdzony arkusz odstępstw (docs/style/nextpdf-overrides.md), który nakłada Apple (ton), Microsoft MSTP (procedury i terminy interfejsu) oraz Google DDSG (kod i CLI) na podstawy prostego języka i słownictwa kontrolowanego, z tabelą rozstrzygania konfliktów dla każdego trybu. Jego najsurowsza reguła jest nadrzędna wobec wszystkich pozostałych: żadnego dosłownego tekstu od licencjonowanej jednostki normalizacyjnej. Każdy punkt, w którym NextPDF odbiega od nadrzędnego przewodnika, jest zapisany wraz z nadrzędną klauzulą, którą zastępuje, oraz powodem. Arkusz stylów cytuje własne źródła w taki sam sposób jak strona.

Jakość, której nie musisz brać na wiarę

Dyscyplina jest egzekwowana przez narzędzia, a nie przez dobre intencje:

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.

Bramki jakości dokumentacji w kolejności, w jakiej strona przez nie przechodzi: wypełniony szkielet ustala strukturę; Vale egzekwuje pakiety stylu; bramki docs:* egzekwują integralność odnośników, higienę cytowań, brak dosłownego tekstu norm oraz brak wycieku prywatnych danych; recenzja potwierdza podstawę dowodową. Strona, która nie przejdzie bramki, jest defektem, traktowanym jak niezaliczony test.

Te punkty odpowiadają rzeczywistym wpisom w composer.json tego repozytorium. docs:lint uruchamia lokalnie bramki NDA i odnośników. docs:jaccard-fingerprint oznacza ponowne użycie dosłownego tekstu norm powyżej progu podobieństwa. docs:rag-fallback-check jest w pełni zaimplementowanym, działającym offline i deterministycznym egzekutorem protokołu integralności cytowań. Ponowna weryfikacja RAG na żywo (docs:rag-citation-check) i część skanerów są podłączone jako bramki, ale ich głębsze moduły uruchomieniowe nadal powstają. Uczciwy stan jest taki: kontrakt został zatwierdzony, a kontrole strukturalne są dziś egzekwowane; prace nad uczynieniem każdej kontroli wyczerpującą trwają. Insider_ nie twierdzi, że ma zielony dashboard, na który nie zapracował — i właśnie tak kryterium „poprawności” modelu jakości działa na tej stronie.

Co mówią dowody

Twierdzenia o jakości dokumentacji na tej stronie mają status Evidence: Standard-backed , a twierdzenia o egzekwowaniu są osadzone w repozytorium. Ta podwójna podstawa jest celowa: zasady pochodzą z norm, a egzekwowanie można zweryfikować, czytając repozytorium.

Twierdzenie	Podstawa	Kotwica
Dokumentacja ma określoną poprzeczkę jakości	Norma	Poprawna, jedno słownictwo, zrozumiała dla czytelnika, potrzebna, lecz kompletna, dostępna dla technologii wspomagających Spec: ISO/IEC/IEEE 26514, §8
Terminologia jest nadzorowana	Norma	Spójna terminologia w całym zbiorze informacji Spec: ISO/IEC/IEEE 26514, §8
Struktura poprzedza pisanie	Norma	Analiza odbiorców i zadań przed projektem Spec: ISO/IEC/IEEE 26514, §9
Najbardziej przydatne stwierdzenie jest pierwsze	Norma	Najważniejszy komunikat na początku Spec: ISO 24495-1, §5
Dokumentacja jest dostarczana z kodem	Norma	Dostarczane elementy każdej iteracji obejmują informacje dla użytkownika Spec: ISO/IEC/IEEE 26515, §Introduction
Jakość jest weryfikowana maszynowo	W repozytorium	`composer.jsondocs:*` — bramki; zatwierdzony `docs/style/nextpdf-overrides.md`; aktywna konfiguracja Vale

Praktyczny przykład

Dyscyplina ujawnia się już w najmniejszej skali: pojedyncza dana jakościowa nigdy nie jest wpisywana ręcznie w tekst, ponieważ liczba umieszczona w treści po cichu się dezaktualizuje. Wyświetla ją komponent, który odmawia wymyślania wartości i korzysta z podstawy dowodowej strony:

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

Kluczowe jest throw. Kryterium „poprawności” modelu jakości informacji nie ma tu charakteru doradczego; struktura je egzekwuje, tak aby nieaktualna liczba nie mogła po cichu trafić na produkcję.

Częste nieporozumienie

Pułapka polega na odczytywaniu „dokumentacji jako produktu” jako hasła o dopracowaniu powierzchni — ładniejszym tekście, ładniejszych stronach. To nie kosmetyka. Oznacza to, że dokumentacja ma określoną poprzeczkę jakości, nadzorowane słownictwo, zamrożoną strukturę oraz bramki weryfikowane maszynowo. Strona, która nie przejdzie którejkolwiek z nich, jest defektem wymagającym poprawki, obsługiwanym jak niezaliczony test. Dopracowanie jest produktem ubocznym dyscypliny, a nie jej celem.

Druga pułapka to założenie, że każda bramka jest już wyczerpująca, skoro istnieje kontrakt. Tak nie jest, a ta strona mówi to wprost. Kontrole strukturalne są egzekwowane już dziś; głębsze weryfikatory są dopiero rozbudowywane. Twierdzenie czegoś innego naruszałoby sam model jakości, który ta strona opisuje.

Ograniczenia i granice

Ta strona opisuje dyscyplinę dokumentacyjną. Nie jest arkuszem stylów, plikiem taksonomii ani samymi implementacjami bramek. Nie deklaruje żadnego zachowania silnika. Miarodajne artefakty znajdują się w repozytorium (docs/style/nextpdf-overrides.md, zamrożona taksonomia, skrypty composer.json docs:*) i mają pierwszeństwo przed tym streszczeniem, jeśli pojawi się rozbieżność.

Zakres egzekwowania jest częściowy, co przyznajemy uczciwie. Awaryjna kontrola integralności cytowań działa. Bramki odnośników i NDA działają lokalnie. Weryfikatory dosłownego cytowania i cytowań na żywo są podłączone, ale ich wyczerpujące moduły uruchomieniowe wciąż są wdrażane. Raportujemy to jako prace w toku, a nie jako ukończone. Tam, gdzie ta strona dotyka dokumentacji warstwy Premium, opisana dyscyplina obowiązuje na poziomie procesu, nigdy na poziomie jakiegokolwiek niepublicznego mechanizmu.

Powiązana dokumentacja

Dyscyplina cytowań — najsurowsza reguła w hierarchii stylów oraz system poziomów dowodów, na którym opiera się ta strona.
Krajobraz norm — normy cytowane przez tę dyscyplinę oraz sposób, w jaki klauzula staje się udokumentowanym zachowaniem.
Filozofia projektowa NextPDF — wyczucie inżynierskie, które traktuje defekt dokumentacji jak defekt kodu.

Słownik pojęć

Model jakości informacji — sposób, w jaki NextPDF przekłada kryteria informacji dla użytkownika z §8 normy ISO 26514 (poprawna, jedno słownictwo, zrozumiała dla czytelnika, potrzebna, lecz kompletna, dostępna dla technologii wspomagających) na poprzeczkę recenzji dla każdej strony Insider_.
Prosty język — komunikacja, której sformułowania, struktura i forma pozwalają docelowym czytelnikom znaleźć, zrozumieć i wykorzystać treść; podstawa stosowana we wszystkich trybach, a nie typ treści.
Hierarchia stylów — zatwierdzony, warstwowy zestaw nadrzędnych przewodników stylu (Apple, Microsoft, Google, plus podstawy prostego języka i słownictwa kontrolowanego), w którym każde odstępstwo NextPDF jest zapisane z odniesieniem do źródła.
Bramka jakości — automatyczna kontrola (pakiet Vale lub skrypt composer docs:*), którą strona musi przejść; niepowodzenie jest defektem dokumentacji, a nie drobiazgiem.
Metadane front-matter — czytelny maszynowo nagłówek (section, audience, evidence_level, tags), który czyni stronę możliwą do odnalezienia i sklasyfikowania, zgodnie z wymogiem organizacji tematów.