Documentação como produto

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

Visão geral

Estas páginas são construídas segundo um modelo de qualidade de documentação, escritas com base em linguagem simples e em uma hierarquia de estilo em camadas, e verificadas pelo mesmo tipo de gates automatizados que rodam no código do engine. Esta página explica essa disciplina e por que o NextPDF registra um defeito de documentação como defeito de engenharia.

Ela foi escrita para um engenheiro sênior que já se frustrou com documentos assertivos, mas impossíveis de verificar, e quer saber o que torna estes diferentes antes de confiar neles.

Por que isso importa

Uma biblioteca de documentos é adotada com base em confiança, e a documentação é onde essa confiança é concedida ou retirada. Uma página errada de um jeito que você não consegue detectar é pior do que nenhuma página. Ela transforma a sua cautela em confiança equivocada. A falha aparece em produção com o seu nome no commit.

A literatura normativa é direta sobre o que está em jogo. Informação para o usuário bem projetada faz mais do que reduzir o custo de suporte; ela melhora a reputação do produto e de quem o produz. Você conquista isso colocando testes de verificação e validação dentro do desenvolvimento, não depois dele Spec: ISO/IEC/IEEE 26513, §Foreword . O NextPDF leva isso ao pé da letra: a documentação é uma superfície de produto com um padrão de qualidade, não uma cortesia anexada ao código.

A versão resumida

O NextPDF submete estes documentos a um modelo de qualidade da informação explícito, derivado dos critérios de informação para o usuário da §8: uma página deve ser tecnicamente precisa, usar um vocabulário consistente, ser compreensível para o leitor declarado, dizer apenas o necessário sem omitir nada exigido e permanecer acessível a tecnologias assistivas Spec: ISO/IEC/IEEE 26514, §8 .
A estrutura não é improvisada. Os tópicos são organizados em uma hierarquia congelada com metadados (seção, público, nível de evidência) para que o leitor os encontre por reconhecimento Spec: ISO/IEC/IEEE 26514, §9 , e a afirmação mais importante fica próxima ao topo de cada página Spec: ISO 24495-1, §5 .
A voz é regida por uma hierarquia de estilo ratificada — Apple para o tom, Microsoft para procedimentos, Google para código, linguagem simples em tudo — registrada no próprio repositório com a cláusula de origem que cada divergência substitui.
A qualidade é verificada por máquina. O Vale aplica os pacotes de voz; um conjunto de gates composer docs:* garante a integridade dos links, a higiene das citações, a ausência de texto literal de normas e a ausência de vazamento de detalhes privados.
Os documentos são desenvolvidos junto com o código, de forma iterativa — cada mudança entrega a documentação correspondente, não um backlog dela Spec: ISO/IEC/IEEE 26515, §Introduction .

Como o NextPDF aborda isso

Um modelo de qualidade, posto por escrito

“Boa documentação” é infalsificável até você nomear os atributos. O NextPDF reformula os critérios de informação para o usuário da §8 em termos próprios como o padrão pelo qual toda página Insider_ é avaliada: cada página deve ser tecnicamente precisa, manter um vocabulário consistente, ser compreensível para o leitor declarado, conter apenas o que esse leitor precisa sem omitir nada exigido e permanecer acessível a tecnologias assistivas Spec: ISO/IEC/IEEE 26514, §8 . Esses não são adjetivos; são critérios de revisão. O teste do “necessário, mas completo” é o motivo de uma página declarar o seu limite e parar, em vez de encher linguiça. A consistência de vocabulário é o motivo de a terminologia ser regida (abaixo). A acessibilidade é o motivo de cada componente ser seguro para teclado e leitor de tela e nunca sinalizar apenas por cor.

Estrutura por análise, não por gosto

A taxonomia Insider_ é congelada antes de qualquer página ser escrita. Isso é deliberado. A ISO 26514 exige que a análise de público e de tarefas preceda o projeto da informação Spec: ISO/IEC/IEEE 26514, §9 . Ela também exige que os tópicos sejam organizados em hierarquias ou grupos, cada um com metadados que identificam o seu público e o tipo de informação, para que você localize rapidamente o que precisa Spec: ISO/IEC/IEEE 26514, §9 . Neste repositório, esses metadados são front-matter concreto — section, audience, evidence_level, tags — e o mapa de clusters é um único arquivo congelado. Você seleciona uma página por reconhecimento; ninguém precisa lembrar um slug.

Dentro de uma página, a ordem é fixa e igual em todos os lugares, e a afirmação mais útil é colocada onde você a encontrará primeiro — geralmente no início Spec: ISO 24495-1, §5 . É por isso que toda página Insider_ coloca A versão resumida antes do detalhe: o leitor pode parar após três seções e ainda sair com uma resposta defensável.

Uma hierarquia de estilo com comprovantes

A voz não fica a cargo do humor do redator. O repositório traz uma planilha de substituições ratificada (docs/style/nextpdf-overrides.md) que sobrepõe Apple (tom), Microsoft MSTP (procedimentos e termos de UI) e Google DDSG (código e CLI) às bases de linguagem simples e vocabulário controlado, com uma tabela de resolução de conflitos por modo. A regra mais rígida dela substitui todas as outras: nenhum texto literal de um organismo de normas licenciado. Todo ponto em que o NextPDF diverge de um guia de origem é registrado com a cláusula de origem que substitui e o motivo. A planilha de estilo cita as próprias fontes do mesmo modo que uma página faz.

Qualidade que você não precisa aceitar na fé

A disciplina é aplicada por ferramentas, não por boas intenções:

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.

Os gates de qualidade da documentação, na ordem em que uma página passa por eles: um scaffold preenchido fixa a estrutura; o Vale aplica os pacotes de voz; os gates docs:* garantem a integridade dos links, a higiene das citações, a ausência de texto literal de normas e a ausência de vazamento privado; a revisão confirma a base de evidências. Uma página que reprova em um gate é um defeito, tratado como um teste reprovado.

Eles correspondem a entradas reais do composer.json deste repositório. O docs:lint roda localmente os gates de NDA e de link. O docs:jaccard-fingerprint sinaliza a reutilização literal de texto de normas acima de um limiar de similaridade. O docs:rag-fallback-check é um aplicador totalmente implementado, offline e determinístico do protocolo de integridade de citações. A reverificação RAG ao vivo (docs:rag-citation-check) e alguns scanners estão integrados como gates, com os seus executores mais profundos ainda em construção. A afirmação honesta é esta: o contrato está ratificado e as verificações estruturais já são aplicadas hoje; a campanha para tornar cada verificação exaustiva continua em andamento. O Insider_ não reivindica um painel verde que não conquistou — o que é, em si, o critério “correto” do modelo de qualidade aplicado a esta página.

O que diz a evidência

Esta página é Evidence: Standard-backed para as afirmações de qualidade de documentação e está fundamentada no repositório para as afirmações de aplicação. A base dupla é deliberada: os princípios vêm das normas; a aplicação pode ser verificada pela leitura do repositório.

Afirmação	Base	Âncora
Os documentos têm um padrão de qualidade definido	Norma	Preciso, vocabulário único, compreensível pelo leitor, necessário mas completo, acessível a tecnologias assistivas Spec: ISO/IEC/IEEE 26514, §8
A terminologia é regida	Norma	Terminologia consistente em todo o conjunto de informação Spec: ISO/IEC/IEEE 26514, §8
A estrutura precede a redação	Norma	Análise de público e de tarefas antes do projeto Spec: ISO/IEC/IEEE 26514, §9
A afirmação mais útil vem primeiro	Norma	Mensagem mais importante no início Spec: ISO 24495-1, §5
Os documentos são entregues com o código	Norma	Os entregáveis de cada iteração incluem informação para o usuário Spec: ISO/IEC/IEEE 26515, §Introduction
A qualidade é verificada por máquina	No repositório	`composer.jsondocs:*` gates; o ratificado `docs/style/nextpdf-overrides.md`; a configuração ativa do Vale

Exemplo prático

A disciplina aparece na menor escala: um dado de qualidade nunca é digitado à mão na prosa, porque um número em texto corrido fica desatualizado silenciosamente. Ele é renderizado por um componente que se recusa a inventar um valor e é respaldado pela base de evidências da página:

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

O essencial é o throw. O critério “correto” do modelo de qualidade da informação não é apenas uma recomendação aqui; a estrutura o aplica para que um número desatualizado não consiga ser publicado silenciosamente.

Equívoco comum

A armadilha é ler “documentação como produto” como um slogan sobre acabamento — prosa mais bonita, páginas mais bem-acabadas. É o oposto de algo cosmético. Significa que os documentos têm um padrão de qualidade definido, um vocabulário regido, uma estrutura congelada e gates verificados por máquina. Uma página que reprova em qualquer um deles é um defeito com correção, tratado como um teste reprovado. O acabamento é subproduto da disciplina, não o seu propósito.

A segunda armadilha é supor que todo gate já é exaustivo só porque o contrato existe. Não é, e esta página diz isso com todas as letras. As verificações estruturais já são aplicadas hoje; os verificadores mais profundos ainda estão sendo construídos. Afirmar o contrário violaria o próprio modelo de qualidade que esta página descreve.

Limites e fronteiras

Esta página descreve a disciplina de documentação. Ela não é a planilha de estilo, o arquivo de taxonomia nem as próprias implementações dos gates. Ela não afirma nenhum comportamento do engine. Os artefatos autoritativos estão no repositório (docs/style/nextpdf-overrides.md, a taxonomia congelada, os scripts composer.json docs:*) e prevalecem sobre qualquer resumo aqui caso divirjam.

A superfície de aplicação é parcial, por admissão honesta. A verificação de fallback de integridade de citações está ativa. Os gates de link e de NDA rodam localmente. Os verificadores de citação literal e de citação ao vivo estão integrados, com os seus executores exaustivos ainda sendo entregues. Isso é reportado como em andamento, não como concluído. Onde esta página toca em documentação de nível Premium, a disciplina descrita se aplica no nível de processo, nunca no nível de qualquer mecanismo não público.

Documentos relacionados

Disciplina de citações — a regra mais rígida da hierarquia de estilo e o sistema de níveis de evidência no qual esta página se apoia.
O panorama das normas — as normas que esta disciplina cita e como uma cláusula se transforma em comportamento documentado.
A filosofia de design do NextPDF — o senso de engenharia que trata defeito de documentação como defeito de código.

Glossário

Modelo de qualidade de informação — a reformulação feita pelo NextPDF dos critérios de informação para o usuário da §8 da ISO 26514 (preciso, vocabulário único, compreensível pelo leitor, necessário mas completo, acessível a tecnologias assistivas), usada como padrão de revisão de toda página Insider_.
Linguagem simples — comunicação cuja redação, estrutura e design permitem que os leitores pretendidos encontrem, entendam e usem o conteúdo; é uma base aplicada a todos os modos, não um tipo de conteúdo.
Hierarquia de estilo — o conjunto ratificado e em camadas de guias de estilo de origem (Apple, Microsoft, Google, mais as bases de linguagem simples e vocabulário controlado), com cada divergência do NextPDF registrada em relação à sua fonte.
Quality gate — uma verificação automatizada (um pacote do Vale ou um script composer docs:*) pela qual uma página deve passar; uma reprovação é um defeito de documentação, não uma implicância.
Metadados de front-matter — o cabeçalho legível por máquina (section, audience, evidence_level, tags) que torna uma página localizável e classificável, conforme o requisito de organização de tópicos.