La documentazione come prodotto

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

In sintesi

Queste pagine seguono un modello di qualità della documentazione, sono scritte in linguaggio chiaro e secondo una gerarchia di stili a più livelli, e sono verificate con lo stesso tipo di controlli automatizzati eseguiti sul codice del motore. Questa pagina descrive tale disciplina e spiega perché un difetto di documentazione viene registrato come un difetto di ingegneria.

Si rivolge a un ingegnere senior che è già rimasto scottato da documentazione assertiva ma non verificabile e vuole capire perché questa sia diversa prima di fidarsene.

Perché è importante

Una libreria documentale si acquista sulla fiducia, e la documentazione è il punto in cui tale fiducia viene concessa o ritirata. Una pagina errata in modo non rilevabile è peggio dell’assenza di pagina. Trasforma la prudenza in una fiducia mal riposta. Il problema emerge in produzione, con il proprio nome sul commit.

La letteratura sugli standard è esplicita riguardo alla posta in gioco. Un’informazione per l’utente ben progettata non riduce soltanto i costi di assistenza, ma migliora la reputazione del prodotto e di chi lo produce. Lo si ottiene collocando i test di verifica e di validazione all’interno dello sviluppo, non dopo di esso Spec: ISO/IEC/IEEE 26513, §Foreword . NextPDF lo prende alla lettera: la documentazione è una superficie di prodotto con un livello di qualità, non una cortesia allegata al codice.

La versione breve

NextPDF sottopone questa documentazione a un esplicito modello di qualità dell’informazione derivato dai criteri di informazione per l’utente del §8: una pagina deve essere tecnicamente accurata, usare un unico vocabolario coerente, essere comprensibile per il lettore dichiarato, dire solo il necessario senza omettere ciò che è richiesto e rimanere raggiungibile dalle tecnologie assistive Spec: ISO/IEC/IEEE 26514, §8 .
La struttura non si improvvisa. Gli argomenti sono organizzati in una gerarchia congelata con metadati (sezione, pubblico, livello di evidenza), così che un lettore possa individuarli per riconoscimento Spec: ISO/IEC/IEEE 26514, §9 , e l’affermazione più importante si trova in cima a ciascuna pagina Spec: ISO 24495-1, §5 .
Il tono è governato da una gerarchia di stili ratificata — Apple per il tono, Microsoft per le procedure, Google per il codice, linguaggio chiaro in tutto — registrata nel repository insieme alla clausola a monte sostituita da ogni divergenza.
La qualità è verificata dalla macchina. Vale applica i pacchetti di tono; una serie di controlli composer docs:* impone l’integrità dei link, l’igiene delle citazioni, l’assenza di testo letterale degli standard e l’assenza di fughe di dettagli riservati.
La documentazione viene sviluppata insieme al codice, in modo iterativo — ogni modifica viene rilasciata con la propria documentazione, non con un arretrato da recuperare Spec: ISO/IEC/IEEE 26515, §Introduction .

Come NextPDF lo affronta

Un modello di qualità, messo per iscritto

«Buona documentazione» è infalsificabile finché non se ne nominano gli attributi. NextPDF riformula i criteri di informazione per l’utente del §8 con parole proprie e li usa come livello rispetto al quale misurare ogni pagina Insider_: ciascuna pagina deve essere tecnicamente accurata, attenersi a un unico vocabolario coerente, essere comprensibile per il lettore a cui si rivolge, riportare solo ciò di cui quel lettore ha bisogno senza omettere nulla di richiesto e rimanere raggiungibile dalle tecnologie assistive Spec: ISO/IEC/IEEE 26514, §8 . Questi non sono aggettivi; sono criteri di revisione. Il criterio del «necessario ma completo» è il motivo per cui una pagina dichiara il proprio limite e si ferma, anziché riempire lo spazio. La coerenza del vocabolario è il motivo per cui la terminologia è governata (più sotto). La raggiungibilità è il motivo per cui ogni componente è utilizzabile da tastiera e da screen reader e non segnala mai con il solo colore.

Struttura per analisi, non per gusto

La tassonomia Insider_ viene congelata prima di scrivere qualsiasi pagina. È una scelta deliberata. ISO 26514 richiede che l’analisi del pubblico e dei compiti preceda la progettazione dell’informazione Spec: ISO/IEC/IEEE 26514, §9 . Richiede inoltre che gli argomenti siano organizzati in gerarchie o gruppi, ciascuno provvisto di metadati che ne identificano il pubblico e il tipo di informazione, così che gli utenti trovino rapidamente ciò di cui hanno bisogno Spec: ISO/IEC/IEEE 26514, §9 . In questo repository tali metadati sono front-matter concreto — section, audience, evidence_level, tags — e la mappa dei cluster è un unico file congelato. Un lettore seleziona una pagina per riconoscimento; non deve mai ricordare uno slug.

All’interno di una pagina, l’ordine è fisso e identico ovunque, e l’affermazione più utile è collocata nel punto in cui un lettore la troverà per prima — di norma all’inizio Spec: ISO 24495-1, §5 . È per questo che ogni pagina Insider_ colloca La versione breve prima del dettaglio: un lettore può fermarsi dopo tre sezioni e uscire comunque con una risposta difendibile.

Una gerarchia di stili con prove a sostegno

Il tono non è lasciato all’umore di chi scrive. Il repository contiene un foglio di override ratificato (docs/style/nextpdf-overrides.md) che sovrappone Apple (tono), Microsoft MSTP (procedure e termini di interfaccia) e Google DDSG (codice e CLI) alle basi del linguaggio chiaro e del vocabolario controllato, con una tabella di risoluzione dei conflitti per ciascuna modalità. La sua regola più rigorosa prevale su tutte le altre: nessun testo letterale tratto da un ente di normazione su licenza. Soprattutto, ogni punto in cui NextPDF diverge da una guida a monte è registrato con la clausola a monte sostituita e con la motivazione. Il foglio di stile cita le proprie fonti nello stesso modo in cui lo fa una pagina.

Una qualità che non occorre prendere sulla fiducia

La disciplina è imposta dagli strumenti, non dalle buone intenzioni:

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.

I controlli di qualità della documentazione, nell'ordine in cui una pagina li supera: uno scaffold popolato fissa la struttura; Vale applica i pacchetti di tono; i controlli docs:* impongono l'integrità dei link, l'igiene delle citazioni, l'assenza di testo letterale degli standard e l'assenza di fughe di dati riservati; la revisione conferma la base di evidenza. Una pagina che non supera un controllo è un difetto, trattato come un test fallito.

Questi controlli corrispondono a voci reali nel composer.json di questo repository. docs:lint esegue localmente i gate NDA e dei link. docs:jaccard-fingerprint segnala il riuso letterale del testo degli standard oltre una soglia di somiglianza. docs:rag-fallback-check applica in modo completo, offline e deterministico il protocollo di integrità delle citazioni. La riverifica RAG in tempo reale (docs:rag-citation-check) e alcuni scanner sono già collegati come gate, mentre i runner più approfonditi sono ancora in costruzione. La dichiarazione onesta è questa: il contratto è ratificato e i controlli strutturali sono applicati oggi; il lavoro per rendere esaustivo ogni controllo è in corso. Insider_ non rivendica un cruscotto verde che non ha conquistato, e questo è a sua volta il criterio «corretto» del modello di qualità applicato a questa pagina.

Cosa dicono le evidenze

Questa pagina è Evidence: Standard-backed per le affermazioni sulla qualità della documentazione e fondata sul repository per le affermazioni sull’applicazione dei controlli. La doppia base è deliberata: i principi vengono dagli standard; l’applicazione è verificabile leggendo il repository.

Affermazione	Fondamento	Ancoraggio
La documentazione ha un livello di qualità definito	Standard	Accuratezza, vocabolario unico, comprensibilità per il lettore, necessario ma completo, raggiungibilità per le tecnologie assistive Spec: ISO/IEC/IEEE 26514, §8
La terminologia è governata	Standard	Terminologia coerente in tutto l’insieme informativo Spec: ISO/IEC/IEEE 26514, §8
La struttura precede la scrittura	Standard	Analisi del pubblico e dei compiti prima della progettazione Spec: ISO/IEC/IEEE 26514, §9
L’affermazione più utile viene per prima	Standard	Messaggio più importante all’inizio Spec: ISO 24495-1, §5
La documentazione viene rilasciata con il codice	Standard	Ogni iterazione include le informazioni per l’utente tra i deliverable Spec: ISO/IEC/IEEE 26515, §Introduction
La qualità è verificata dalla macchina	Nel repository	controlli `composer.jsondocs:*`; foglio ratificato `docs/style/nextpdf-overrides.md`; configurazione Vale attiva

Esempio pratico

La disciplina si manifesta anche alla scala più piccola: un dato di qualità non viene mai digitato a mano nella prosa, perché un numero nella prosa diventa obsoleto in silenzio. Lo rende un componente che si rifiuta di inventare un valore e si appoggia alla base di evidenza della pagina:

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

Il punto cruciale è il throw. Il criterio «corretto» del modello di qualità dell’informazione qui non è consultivo; è imposto strutturalmente, così che un dato obsoleto non possa essere rilasciato in silenzio.

Equivoco comune

La trappola è leggere «la documentazione come prodotto» come uno slogan sulla rifinitura — una prosa più curata, pagine più gradevoli. Non è una questione cosmetica. Significa che la documentazione porta con sé un livello di qualità definito, un vocabolario governato, una struttura congelata e controlli verificati dalla macchina, e che una pagina che non supera uno qualsiasi di essi è un difetto da correggere, gestito come un test fallito. La rifinitura è un sottoprodotto della disciplina, non il suo scopo.

La seconda trappola è dare per scontato che ogni controllo sia già esaustivo per il solo fatto che il contratto esiste. Non lo è, e questa pagina lo dichiara apertamente. I controlli strutturali sono già applicati oggi; i verificatori più approfonditi sono in corso di sviluppo. Affermare il contrario violerebbe il modello di qualità stesso che questa pagina descrive.

Limiti e confini

Questa pagina descrive la disciplina della documentazione. Non è il foglio di stile, il file della tassonomia né le implementazioni dei controlli stessi. Non afferma alcun comportamento del motore. Gli artefatti autorevoli si trovano nel repository (docs/style/nextpdf-overrides.md, la tassonomia congelata, gli script docs:* in composer.json) e prevalgono su qualsiasi sintesi qui presente in caso di divergenza.

L’applicazione è dichiaratamente parziale. Il controllo di fallback sull’integrità delle citazioni è attivo. I controlli sui link e sull’NDA vengono eseguiti localmente. I verificatori delle citazioni letterali e delle citazioni in tempo reale sono collegati, ma i loro esecutori esaustivi non sono ancora disponibili. Questo è indicato come lavoro in corso, non come completato. Laddove questa pagina tocca la documentazione del livello Premium, la disciplina descritta si applica al livello del processo, mai al livello di alcun meccanismo non pubblico.

Documentazione correlata

Disciplina delle citazioni — la regola più rigorosa della gerarchia di stili e il sistema dei livelli di evidenza su cui questa pagina si basa.
Il panorama degli standard — gli standard citati da questa disciplina e il modo in cui una clausola diventa comportamento documentato.
La filosofia di progettazione di NextPDF — il criterio ingegneristico che tratta un difetto di documentazione come un difetto di codice.

Glossario

Modello di qualità dell’informazione — la riformulazione di NextPDF dei criteri di informazione per l’utente del §8 di ISO 26514 (accurato, a vocabolario unico, comprensibile per il lettore, necessario ma completo, raggiungibile dalle tecnologie assistive) usata come criterio di revisione per ogni pagina Insider_.
Linguaggio chiaro — una comunicazione la cui formulazione, struttura e presentazione consentono ai lettori previsti di trovare, comprendere e usare il contenuto; una base applicata a tutte le modalità, non un tipo di contenuto.
Gerarchia di stili — l’insieme ratificato e a più livelli delle guide di stile a monte (Apple, Microsoft, Google, oltre alle basi di linguaggio chiaro e vocabolario controllato), con ogni divergenza di NextPDF registrata rispetto alla propria fonte.
Controllo di qualità — una verifica automatizzata (un pacchetto Vale o uno script composer docs:*) che una pagina deve superare; un fallimento è un difetto di documentazione, non un’inezia.
Metadati del front-matter — l’intestazione leggibile dalla macchina (section, audience, evidence_level, tags) che rende una pagina localizzabile e classificabile, secondo il requisito di organizzazione degli argomenti.