La documentación como producto

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

De un vistazo

Estas páginas se construyen con un modelo de calidad de la documentación, una base de lenguaje claro, una jerarquía de estilo por capas y controles automatizados del mismo tipo que los que se ejecutan sobre el código del motor. Esta página explica esa disciplina y por qué un defecto de documentación se registra como un defecto de ingeniería.

Está escrita para una persona con experiencia en ingeniería que ya ha lidiado con documentación tajante pero imposible de verificar, y que quiere saber qué hace diferente a esta antes de confiar en ella.

Por qué esto importa

Una biblioteca se adopta por confianza, y la documentación es donde esa confianza se concede o se retira. Una página equivocada de una forma que no se puede detectar es peor que no tener página alguna. Convierte la cautela en confianza mal depositada. El fallo aparece en producción con su nombre en el commit.

La literatura normativa es tajante en cuanto a lo que está en juego. Una información para el usuario bien diseñada no solo reduce el coste de soporte: refuerza la reputación del producto y de quien lo produce. Eso se gana incorporando las pruebas de verificación y validación durante el desarrollo, no después de él Spec: ISO/IEC/IEEE 26513, §Foreword . NextPDF se lo toma al pie de la letra: la documentación es una superficie de producto con un listón de calidad, no una cortesía añadida al código.

La versión breve

NextPDF somete esta documentación a un modelo de calidad de la información explícito, derivado de los criterios de información para el usuario del §8: una página debe ser técnicamente exacta, emplear un vocabulario coherente, ser comprensible para el lector al que se dirige, decir solo lo necesario sin omitir nada de lo exigido y seguir siendo accesible para la tecnología de apoyo Spec: ISO/IEC/IEEE 26514, §8 .
La estructura no se improvisa. Los temas se organizan en una jerarquía congelada con metadatos (sección, audiencia, nivel de evidencia) para que un lector pueda localizar cada uno por reconocimiento Spec: ISO/IEC/IEEE 26514, §9 , y la afirmación más importante se sitúa cerca del comienzo de cada página Spec: ISO 24495-1, §5 .
La voz se rige por una jerarquía de estilo ratificada —Apple para el tono, Microsoft para los procedimientos, Google para el código y lenguaje claro en todo el conjunto— registrada en el repositorio junto con la cláusula original que cada divergencia anula.
La calidad se comprueba por máquina. Vale aplica los paquetes de voz; un conjunto de controles composer docs:* impone la integridad de los enlaces, la higiene de las citas, la ausencia de texto literal de normas y la ausencia de filtraciones de detalles privados.
La documentación se desarrolla junto con el código, de forma iterativa: cada cambio entrega su documentación, no una deuda documental acumulada Spec: ISO/IEC/IEEE 26515, §Introduction .

Cómo lo aborda NextPDF

Un modelo de calidad, puesto por escrito

«Buena documentación» es infalsable hasta que se nombran sus atributos. NextPDF reformula en sus propios términos los criterios de información para el usuario del §8 como el listón con el que se mide cada página Insider_: cada página debe ser técnicamente exacta, mantener un vocabulario coherente, ser comprensible para el lector al que se dirige, contener solo lo que ese lector necesita sin omitir nada de lo exigido y seguir siendo accesible para la tecnología de apoyo Spec: ISO/IEC/IEEE 26514, §8 . No son adjetivos; son criterios de revisión. El criterio de «lo necesario, pero completo» es la razón por la que una página declara su límite y se detiene, en lugar de rellenar espacio. La coherencia del vocabulario es la razón por la que la terminología está gobernada (más abajo). La accesibilidad es la razón por la que cada componente es seguro para el teclado y para el lector de pantalla, y nunca señaliza únicamente mediante el color.

Estructura por análisis, no por gusto

La taxonomía Insider_ se congela antes de escribir ninguna página. Esto es deliberado. ISO 26514 exige que el análisis de la audiencia y de las tareas preceda al diseño de la información Spec: ISO/IEC/IEEE 26514, §9 . También exige que los temas se organicen en jerarquías o grupos, cada uno con metadatos que identifican su audiencia y su tipo de información, para que los usuarios localicen rápidamente lo que necesitan Spec: ISO/IEC/IEEE 26514, §9 . En este repositorio esos metadatos son front-matter concreto —section, audience, evidence_level, tags— y el mapa de clústeres es un único archivo congelado. Un lector selecciona una página por reconocimiento; nunca tiene que recordar un slug.

Dentro de una página, el orden es fijo y se mantiene en todas partes, y la afirmación más útil se coloca donde el lector la encontrará primero, normalmente al principio Spec: ISO 24495-1, §5 . Por eso cada página Insider_ coloca La versión breve antes del detalle: un lector puede detenerse tras tres secciones y aun así llevarse una respuesta defendible.

Una jerarquía de estilo con comprobantes

La voz no se deja al estado de ánimo del redactor. El repositorio incluye una hoja de excepciones ratificada (docs/style/nextpdf-overrides.md) que superpone Apple (tono), Microsoft MSTP (procedimientos y términos de interfaz) y Google DDSG (código y CLI) sobre las bases de lenguaje claro y vocabulario controlado, con una tabla de resolución de conflictos por modo. Su regla más estricta prevalece sobre todas las demás: nada de texto literal de un organismo de normalización con licencia. Lo fundamental: cada punto en el que NextPDF diverge de una guía original queda registrado junto con la cláusula original que anula y el motivo. La hoja de estilo cita sus propias fuentes del mismo modo que lo hace una página.

Calidad que no hace falta creer por fe

La disciplina la imponen las herramientas, no las buenas intenciones:

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.

Los controles de calidad de la documentación, en el orden en que una página los supera: un andamiaje poblado fija la estructura; Vale aplica los paquetes de voz; los controles docs:* imponen la integridad de los enlaces, la higiene de las citas, la ausencia de texto literal de normas y la ausencia de fugas privadas; la revisión confirma la base de evidencia. Una página que no supera un control es un defecto, tratado como una prueba fallida.

Estos controles corresponden a entradas reales del composer.json de este repositorio. docs:lint ejecuta localmente los controles de NDA y enlaces. docs:jaccard-fingerprint marca la reutilización literal de texto de normas por encima de un umbral de similitud. docs:rag-fallback-check es un verificador del protocolo de integridad de citas plenamente implementado, sin conexión y determinista. La reverificación RAG en vivo (docs:rag-citation-check) y algunos escáneres están conectados como controles, aunque sus ejecutores más profundos aún se están desarrollando. La formulación honesta es esta: el contrato está ratificado y las comprobaciones estructurales se aplican hoy; la campaña para hacer exhaustiva cada comprobación sigue en curso. Insider_ no afirma tener un panel en verde que no se ha ganado, lo que ya es aplicar a esta página el criterio de «correcto» del modelo de calidad.

Qué dice la evidencia

Esta página cuenta con Evidence: Standard-backed para las afirmaciones sobre calidad de la documentación y se apoya en el repositorio para las afirmaciones sobre aplicación de controles. La doble base es deliberada: los principios provienen de normas; la aplicación puede verificarse leyendo el repositorio.

Afirmación	Base	Ancla
La documentación tiene un listón de calidad definido	Norma	Exacta, con vocabulario único, comprensible para el lector, necesaria pero completa y accesible para la tecnología de apoyo Spec: ISO/IEC/IEEE 26514, §8
La terminología está gobernada	Norma	Terminología coherente en todo el conjunto de información Spec: ISO/IEC/IEEE 26514, §8
La estructura precede a la redacción	Norma	Análisis de audiencia y tareas antes del diseño Spec: ISO/IEC/IEEE 26514, §9
La afirmación más útil va primero	Norma	Mensaje más importante al comienzo Spec: ISO 24495-1, §5
La documentación se entrega con el código	Norma	Los entregables de cada iteración incluyen información para el usuario Spec: ISO/IEC/IEEE 26515, §Introduction
La calidad se comprueba por máquina	En el repositorio	controles `composer.jsondocs:*`; el ratificado `docs/style/nextpdf-overrides.md`; la configuración activa de Vale

Ejemplo práctico

La disciplina se manifiesta a la escala más pequeña: un dato de calidad nunca se escribe a mano en la prosa, porque un número en la prosa queda obsoleto en silencio. Lo representa un componente que se niega a inventar un valor y está respaldado por la base de evidencia de la 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');

La clave está en el throw. El criterio «correcto» del modelo de calidad de la información no funciona aquí como una recomendación; se impone de forma estructural para que una cifra obsoleta no pueda publicarse en silencio.

Error frecuente

La trampa está en leer «la documentación como producto» como un eslogan sobre pulido: una prosa más cuidada, páginas más bonitas. Es lo contrario de algo cosmético. Significa que la documentación tiene un listón de calidad definido, un vocabulario gobernado, una estructura congelada y controles comprobados por máquina, y que una página que falla en cualquiera de ellos es un defecto que debe corregirse, tratado como una prueba fallida. El pulido es un subproducto de la disciplina, no su propósito.

La segunda trampa es suponer que cada control ya es exhaustivo solo porque el contrato existe. No lo es, y esta página lo dice con claridad. Las comprobaciones estructurales se imponen hoy; los verificadores más profundos se están construyendo. Afirmar lo contrario vulneraría el propio modelo de calidad que describe esta página.

Límites y fronteras

Esta página describe la disciplina de documentación. No es la hoja de estilo, el archivo de taxonomía ni las propias implementaciones de los controles. No afirma ningún comportamiento del motor. Los artefactos autorizados están en el repositorio (docs/style/nextpdf-overrides.md, la taxonomía congelada, los scripts composer.json docs:*) y prevalecen sobre cualquier resumen incluido aquí si divergen.

El ámbito de aplicación es parcial, y se admite con honestidad. La comprobación de respaldo de integridad de las citas está activa. Los controles de enlaces y de NDA se ejecutan localmente. Los verificadores de citas literales y de citas en vivo están cableados, mientras sus ejecutores exhaustivos siguen en desarrollo. Esto se informa como en curso, no como terminado. Allí donde esta página roza la documentación de nivel Premium, la disciplina descrita se aplica en el plano del proceso, nunca en el de ningún mecanismo no público.

Documentación relacionada

Disciplina de citas: la regla más estricta de la jerarquía de estilo y el sistema de niveles de evidencia en el que se apoya esta página.
El panorama de las normas: las normas que cita esta disciplina y cómo una cláusula se convierte en comportamiento documentado.
La filosofía de diseño de NextPDF: el criterio de ingeniería que trata un defecto de documentación como un defecto de código.

Glosario

Modelo de calidad de la información: la reformulación que hace NextPDF de los criterios de información para el usuario del §8 de ISO 26514 (exacta, con vocabulario único, comprensible para el lector, necesaria pero completa y accesible para la tecnología de apoyo) empleada como listón de revisión para cada página Insider_.
Lenguaje claro: comunicación cuya redacción, estructura y diseño permiten a los lectores previstos encontrar, comprender y usar el contenido; una base aplicada a todos los modos, no un tipo de contenido.
Jerarquía de estilo: el conjunto ratificado y por capas de guías de estilo originales (Apple, Microsoft, Google, más las bases de lenguaje claro y vocabulario controlado), con cada divergencia de NextPDF registrada frente a su fuente.
Control de calidad: una comprobación automatizada (un paquete de Vale o un script composer docs:*) que una página debe superar; un fallo es un defecto de documentación, no un detalle menor.
Metadatos de front-matter: la cabecera legible por máquina (section, audience, evidence_level, tags) que hace que una página sea localizable y clasificable, conforme al requisito de organización de los temas.