Документация как продукт

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

Кратко

Эти страницы построены по модели качества документации, написаны с опорой на базовый уровень ясного языка и многоуровневую иерархию стиля и проходят те же автоматические проверки, что и код движка. Эта страница объясняет такую дисциплину и то, почему NextPDF регистрирует дефект документации как инженерный дефект.

Она написана для опытного инженера, который уже обжёгся на самоуверенной, непроверяемой документации и хочет понять, чем отличается эта, прежде чем ей доверять.

Почему это важно

Библиотеку для работы с документами покупают, доверяя ей, и именно документация — место, где это доверие подтверждается или исчезает. Страница с ошибкой, которую вы не можете заметить, хуже, чем отсутствие страницы. Она превращает вашу осторожность в неоправданную уверенность. Сбой проявляется в продакшене, а в коммите стоит ваше имя.

Стандарты прямо говорят, что поставлено на карту. Хорошо продуманная информация для пользователей не только снижает затраты на поддержку, но и укрепляет репутацию продукта и его производителя. Для этого проверку и валидационное тестирование встраивают в процесс разработки, а не выполняют после него Spec: ISO/IEC/IEEE 26513, §Foreword . NextPDF воспринимает это буквально: документация — это часть продукта с планкой качества, а не любезное дополнение к коду.

Если коротко

NextPDF применяет к этой документации явную модель качества информации, выведенную из критериев пользовательской информации §8: страница должна быть технически точной, использовать единую последовательную терминологию, быть понятной заявленному читателю, сообщать только необходимое и при этом не упускать ничего обязательного, а также оставаться доступной для ассистивных технологий Spec: ISO/IEC/IEEE 26514, §8 .
Структура не импровизируется. Темы упорядочены в зафиксированную иерархию с метаданными (раздел, аудитория, уровень доказательности), чтобы читатель мог найти нужную страницу по знакомым признакам Spec: ISO/IEC/IEEE 26514, §9 , а самое важное утверждение располагается ближе к началу каждой страницы Spec: ISO 24495-1, §5 .
Тон задаётся утверждённой иерархией стиля — Apple для тона, Microsoft для процедур, Google для кода, ясный язык во всём — зафиксированной в репозитории вместе с исходным пунктом, который замещает каждое отклонение.
Качество проверяется машинно. Vale обеспечивает соблюдение пакетов голоса; набор проверок composer docs:* контролирует целостность ссылок, гигиену цитирования, отсутствие дословного текста стандартов и отсутствие утечки приватных сведений.
Документация разрабатывается вместе с кодом, итеративно — каждое изменение поставляется со своей документацией, а не откладывается в бэклог Spec: ISO/IEC/IEEE 26515, §Introduction .

Как к этому подходит NextPDF

Модель качества, зафиксированная явно

“Хорошая документация” непроверяема, пока вы не назовёте её атрибуты. NextPDF формулирует критерии пользовательской информации §8 своими словами как планку, по которой оценивается каждая страница Insider_: каждая страница должна быть технически точной, придерживаться единой последовательной терминологии, быть понятной заявленному читателю, нести только то, что этому читателю нужно, не упуская ничего обязательного, и оставаться доступной для ассистивных технологий Spec: ISO/IEC/IEEE 26514, §8 . Это не прилагательные, а критерии проверки. Критерий “необходимое, но полное” объясняет, почему страница обозначает свою границу и останавливается, а не разбавляется лишним. Последовательность словаря — причина того, что терминология управляется (см. ниже). Доступность — причина того, что каждый компонент безопасен для клавиатуры и программ чтения с экрана и никогда не передаёт смысл только цветом.

Структура на основе анализа, а не вкуса

Таксономия Insider_ фиксируется до того, как будет написана хоть одна страница. Это сделано намеренно. ISO 26514 требует, чтобы анализ аудитории и задач предшествовал проектированию информации Spec: ISO/IEC/IEEE 26514, §9 . Он также требует, чтобы темы были организованы в иерархии или группы, каждая из которых несёт метаданные, определяющие её аудиторию и тип информации, чтобы пользователи быстро находили нужное Spec: ISO/IEC/IEEE 26514, §9 . В этом репозитории такие метаданные — это конкретный front-matter: section, audience, evidence_level, tags — а карта кластеров представляет собой единый зафиксированный файл. Читатель выбирает страницу по знакомым признакам; никому не нужно вспоминать slug.

Внутри страницы порядок зафиксирован и одинаков везде, а самое полезное утверждение размещается там, где читатель найдёт его первым — обычно в начале Spec: ISO 24495-1, §5 . Именно поэтому каждая страница Insider_ помещает Если коротко перед подробностями: читатель может остановиться после трёх разделов и всё равно получить обоснованный ответ.

Иерархия стиля с подтверждениями

Тон не отдаётся на откуп настроению автора. В репозитории есть утверждённый файл переопределений (docs/style/nextpdf-overrides.md), который надстраивает Apple (тон), Microsoft MSTP (процедуры и термины интерфейса) и Google DDSG (код и CLI) над базовыми уровнями ясного языка и контролируемого словаря, с таблицей разрешения конфликтов для каждого режима. Его самое строгое правило замещает все остальные: никакого дословного текста из лицензированного органа по стандартизации. Каждое место, где NextPDF отклоняется от вышестоящего руководства, фиксируется вместе с исходным пунктом, который оно замещает, и причиной. Лист стиля ссылается на собственные источники так же, как это делает страница.

Качество, которое не нужно принимать на веру

Дисциплину обеспечивает инструментарий, а не добрые намерения:

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.

Проверки качества документации в том порядке, в котором их проходит страница: заполненный каркас закрепляет структуру; Vale обеспечивает соблюдение пакетов голоса; проверки docs:* контролируют целостность ссылок, гигиену цитирования, отсутствие дословного текста стандартов и отсутствие утечки приватных сведений; рецензирование подтверждает доказательную базу. Страница, не прошедшая проверку, — это дефект, с которым обращаются как с непройденным тестом.

Они соответствуют реальным записям в composer.json этого репозитория. docs:lint запускает проверки NDA и ссылок локально. docs:jaccard-fingerprint отмечает дословное переиспользование текста стандартов выше порога схожести. docs:rag-fallback-check — полностью реализованный, офлайновый, детерминированный исполнитель протокола целостности цитирования. Повторная RAG-проверка в реальном времени (docs:rag-citation-check) и некоторые сканеры подключены как проверки, а их более глубокие исполнители ещё дорабатываются. Честная формулировка такова: контракт утверждён, и структурные проверки действуют уже сегодня; работа над тем, чтобы каждая проверка стала исчерпывающей, продолжается. Insider_ не заявляет о зелёной панели, которую он не заслужил, — а это и есть критерий “корректности” модели качества, применённый к этой странице.

Фиксированная форма из десяти разделов, ряд значков и размещение короткого ответа ближе к началу — это не фирменный стиль ради него самого. Так в материале воплощаются ясный язык и модель качества информации. Последовательная структура позволяет вернувшемуся читателю просматривать страницу по знакомым признакам, а не изучать её заново. Размещение самого важного сообщения первым напрямую применяет рекомендацию, которая помогает читателям быстрее находить нужное. Дисциплина, о которой вы читаете, — это та самая дисциплина, по которой написана эта страница.

Что подтверждают свидетельства

Эта страница имеет статус Evidence: Standard-backed для утверждений о качестве документации и опирается на репозиторий для утверждений о контроле. Двойная основа выбрана намеренно: принципы взяты из стандартов; контроль проверяется чтением репозитория.

Утверждение	Основа	Якорь
У документации есть заданная планка качества	Стандарт	Точная, с единым словарём, понятная читателю, необходимая, но полная, доступная для ассистивных технологий Spec: ISO/IEC/IEEE 26514, §8
Терминология управляется	Стандарт	Последовательная терминология по всему набору информации Spec: ISO/IEC/IEEE 26514, §8
Структура предшествует написанию	Стандарт	Анализ аудитории и задач до проектирования Spec: ISO/IEC/IEEE 26514, §9
Самое полезное утверждение идёт первым	Стандарт	Самое важное сообщение в начале Spec: ISO 24495-1, §5
Документация поставляется вместе с кодом	Стандарт	В состав поставки каждой итерации входит информация для пользователей Spec: ISO/IEC/IEEE 26515, §Introduction
Качество проверяется машинно	В репозитории	`composer.jsondocs:*` — проверки; утверждённый `docs/style/nextpdf-overrides.md`; активная конфигурация Vale

Практический пример

Дисциплина проявляется даже в мелочах: показатель качества никогда не вписывается в текст вручную, потому что число в тексте незаметно устаревает. Его отрисовывает компонент, который отказывается выдумывать значение и опирается на доказательную базу страницы:

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

Суть — в throw. Критерий “корректности” модели качества информации здесь не рекомендательный; структура обеспечивает его выполнение, чтобы устаревшее значение не могло незаметно попасть в поставку.

Частое заблуждение

Ловушка в том, чтобы прочитать “документацию как продукт” как лозунг о лоске: более красивый текст, более нарядные страницы. Это полная противоположность косметике. Это означает, что у документации есть чётко заданная планка качества, управляемый словарь, зафиксированная структура и машинно проверяемые проверки. Страница, не прошедшая любую из них, — это дефект с исправлением, с которым обращаются как с непройденным тестом. Лоск — побочный продукт дисциплины, а не её цель.

Вторая ловушка — считать, что каждая проверка уже исчерпывающа, раз контракт существует. Это не так, и эта страница прямо об этом говорит. Структурные проверки действуют уже сегодня; более глубокие верификаторы находятся в разработке. Утверждать иное означало бы нарушить ту самую модель качества, которую описывает эта страница.

Ограничения и границы

Эта страница описывает дисциплину документации. Это не лист стиля, не файл таксономии и не сами реализации проверок. Она не утверждает никакого поведения движка. Авторитетные артефакты находятся в репозитории (docs/style/nextpdf-overrides.md, зафиксированная таксономия, скрипты composer.json docs:*) и имеют приоритет над любым резюме на этой странице, если между ними есть расхождения.

Область контроля частична — это признаётся прямо. Резервная проверка целостности цитирования работает. Проверки ссылок и NDA выполняются локально. Верификаторы дословных цитат и проверки цитирования в реальном времени подключены, но их исчерпывающие исполнители ещё дорабатываются. Об этом говорится как о работе в процессе, а не как о завершённой. Там, где эта страница затрагивает документацию уровня Premium, описанная дисциплина применяется на уровне процесса, но никогда на уровне какого-либо непубличного механизма.

Связанная документация

Дисциплина цитирования — самое строгое правило в иерархии стиля и система уровней доказательности, на которые опирается эта страница.
Ландшафт стандартов — стандарты, на которые ссылается эта дисциплина, и то, как пункт становится задокументированным поведением.
Философия проектирования NextPDF — инженерный вкус, который относится к дефекту документации как к дефекту кода.

Глоссарий

Модель качества информации — переформулировка критериев пользовательской информации ISO 26514 §8 в NextPDF (точная, с единым словарём, понятная читателю, необходимая, но полная, доступная для ассистивных технологий), используемая как планка проверки для каждой страницы Insider_.
Ясный язык — коммуникация, формулировки, структура и оформление которой позволяют целевым читателям находить, понимать и использовать содержание; базовый уровень, применяемый ко всем режимам, а не тип контента.
Иерархия стиля — утверждённый многоуровневый набор вышестоящих руководств по стилю (Apple, Microsoft, Google, а также базовые уровни ясного языка и контролируемого словаря), в котором каждое отклонение NextPDF зафиксировано относительно своего источника.
Проверка качества — автоматическая проверка (пакет Vale или скрипт composer docs:*), которую страница должна пройти; непрохождение — это дефект документации, а не мелочь.
Метаданные front-matter — машиночитаемый заголовок (section, audience, evidence_level, tags), который делает страницу находимой и классифицируемой согласно требованию к организации тем.