Disciplina delle citazioni

Spec: ISO/IEC/IEEE 26514 Spec: ISO 24495-1 Evidence: Editorial

In sintesi

Questa è la pagina a cui rimanda il resto di Insider_ quando parla di “livello di evidenza”. Spiega perché questa documentazione parafrasa gli standard invece di citarli, come ogni affermazione si collega a un ID di riferimento riverificabile e che cosa, con precisione, ciascuno degli otto livelli di evidenza promette e non promette.

È scritta per un ingegnere esperto che, prima di fidarsi di un’affermazione, vuole conoscere le regole secondo cui è stata formulata, e ha ragione a volerlo.

Perché è importante

Ogni altra pagina di Insider_ formula affermazioni e le contrassegna con un livello di evidenza. Quel contrassegno vale solo se il sistema che lo sostiene è esplicito. Se “supportato da standard” potesse significare qualunque cosa, da “ho letto la specifica con attenzione” a “ricordo grosso modo cosa diceva”, il badge sarebbe solo decorazione.

Esiste anche un vincolo più rigido. Molti dei documenti a cui NextPDF risponde — le specifiche ISO, ETSI e simili — sono soggetti a licenza. Riprodurne il testo, di qualsiasi lunghezza, non è consentito. Perciò la disciplina deve risolvere due problemi contemporaneamente: rendere un’affermazione verificabile rispetto alla sua fonte senza riprodurre quella fonte. La risposta a entrambi i problemi è lo stesso meccanismo, e questa pagina ne è la specifica.

La versione breve

Insider_ parafrasa gli standard e non cita mai quelli soggetti a licenza. Un’affermazione indica lo standard, la clausola e un ID di riferimento; non riproduce le parole dello standard.
La parafrasi non è un escamotage; è un test di comprensione. Riformulare un requisito con la voce di NextPDF costringe chi scrive a comprenderlo e mantiene la terminologia coerente con il glossario Spec: ISO/IEC/IEEE 26514, §8 .
Ogni affermazione supportata da standard porta con sé un reference_id di 64 caratteri nel front-matter citations della pagina, così che il revisore successivo possa recuperare nuovamente l’esatto intervallo della fonte e confermare la parafrasi.
Il badge dichiara un livello di evidenza — uno di otto tipi — che indica il tipo di prova, così che un’affermazione eccessiva sia visibile a colpo d’occhio.
Quando la fonte non può essere recuperata, l’affermazione non viene falsificata. Viene mantenuta, contrassegnata come irrisolta rispetto a un registro di ri-ancoraggio, e la pagina resta non pubblicata — un protocollo documentato, non un’improvvisazione.

Come NextPDF lo affronta

Parafrasi, non citazione

La regola più rigida nella gerarchia stilistica di NextPDF prevale su ogni guida a monte: nessun testo letterale tratto da un ente di normazione soggetto a licenza, indipendentemente da quanto breve sia l’estratto. Invece, una pagina indica lo standard e la clausola, parafrasa il requisito con la propria voce e registra l’ID di riferimento della fonte.

Di solito lo si inquadra come un vincolo di licenza, e lo è. Ma l’inquadramento più utile è editoriale. Una citazione letterale dimostra soltanto che si è capaci di copiare. Una parafrasi fedele dimostra che si è compresa la clausola abbastanza bene da riformularla senza alterarne il significato. Inoltre consente alla frase di restare nel vocabolario coerente di NextPDF, anziché cambiare registro a metà pagina, come richiede il modello di qualità della documentazione Spec: ISO/IEC/IEEE 26514, §8 . Il linguaggio chiaro si giudica dalla capacità del lettore di trovare, comprendere e usare il contenuto, non dalla somiglianza della prosa alla fonte Spec: ISO 24495-1, §Introduction ; la parafrasi serve a questo, la citazione no.

Un’affermazione è legata a un ID di riferimento, non a un ricordo

Il meccanismo che rende verificabile una parafrasi è l’ID di riferimento. Ogni affermazione supportata da standard porta con sé un reference_id completo di 64 caratteri nel front-matter citations della pagina, che identifica l’esatto intervallo della fonte da cui è stata tratta la parafrasi. Un revisore non deve fidarsi della memoria di chi scrive: recupera nuovamente quell’intervallo e confronta. L’ID di riferimento è il collegamento tra una fonte non citabile e un’affermazione verificabile. Porta con sé dove si trova la prova senza portarne il testo.

Il livello di evidenza indica di che tipo di prova si tratta

Una citazione risponde a “da dove”. Il livello di evidenza risponde a “di che tipo”. Ogni pagina di Insider_ ne dichiara uno, mostrato nella riga dei badge e tratto da un insieme fisso di otto. L’ordine di affidabilità colloca il codice e i test sopra il runtime, il runtime sopra i metadati e i metadati sopra la prosa; una pagina editoriale non finge di essere supportata dal codice.

Livello di evidenza	Cosa promette	Cosa non promette
Evidence: Code-backed	L’affermazione è verificata rispetto al sorgente del motore o a un esempio eseguibile	Che uno standard lo imponga
Evidence: Standard-backed	L’affermazione è ancorata a una clausola citata e parafrasata con un ID di riferimento	Che il codice attualmente la implementi senza eccezioni
Evidence: Test-backed	Un test nella suite preserva quel comportamento	Una cifra prestazionale
Evidence: Benchmark-backed	Una misurazione secondo un metodo dichiarato supporta la cifra	La stessa cifra sul vostro hardware
Evidence: Artifact-backed	Un artefatto prodotto (un output di build, un report) lo dimostra	Un mandato normativo
Evidence: Design principle	Una decisione di progettazione deliberata e argomentata	Una misurazione empirica
Evidence: Editorial	Una spiegazione ragionata che organizza altre evidenze	Una nuova garanzia comportamentale autonoma
Evidence: Mixed evidence	La pagina combina più basi e indica quale vale per ciascuna affermazione	Una base unica e distinta

Questa pagina è Evidence: Editorial : non afferma alcun comportamento proprio del motore. Spiega il sistema su cui si basano i badge delle altre pagine. Questo è il livello onesto per essa, e dichiararlo significa applicare la disciplina a se stessa.

Quando la fonte non può essere recuperata

Il recupero non è sempre disponibile. L’integrità della disciplina si vede in ciò che accade allora. Una coda ordinaria, un limite di frequenza o una pausa di budget non è un’interruzione del servizio. Chi scrive attende. Un’interruzione effettiva attiva un fallback documentato: l’affermazione viene mantenuta, collegata alle evidenze interne al repository e ai riferimenti normativi che il codice stesso dichiara, contrassegnata esplicitamente come irrisolta rispetto a un registro permanente di ri-ancoraggio, e la pagina resta non pubblicata finché l’ID di riferimento non è realmente ancorato.

Le mosse proibite sono enumerate e verificabili: un ID di riferimento fabbricato, un valore di riempimento o con prefisso per sembrare reale, una clausola scritta a memoria e travestita da citazione recuperata, oppure la cancellazione silenziosa dell’affermazione per eludere la citazione. Un’interruzione correttamente contrassegnata su una bozza è debito tracciato da una voce di registro, non un difetto. Un controllo offline e deterministico applica esattamente questa distinzione.

Cosa dicono le evidenze

Questa pagina è Evidence: Editorial , quindi la sua base è la governance della documentazione in questo repository, insieme agli standard che giustificano la disciplina. Le affermazioni qui presenti sono verificabili in due modi: leggendo le regole interne al repository e recuperando nuovamente le clausole citate.

Affermazione	Base	Ancora
La parafrasi costringe alla comprensione	Standard	Linguaggio chiaro giudicato dall’uso che ne fa il lettore, non dal rispecchiamento della fonte Spec: ISO 24495-1, §Introduction
La terminologia resta coerente	Standard	Ciascun termine usato in modo coerente in tutto il documento Spec: ISO/IEC/IEEE 26514, §8
La revisione fa parte del processo	Standard	Test di verifica e validazione all’interno dello sviluppo Spec: ISO/IEC/IEEE 26513, §Foreword
Il livello di evidenza è riconoscibile per primo	Standard	Riconoscimento anziché richiamo mnemonico Spec: ISO 9241-110, §5.6.2
Nessun testo letterale soggetto a licenza; ancorato a riferimenti	Interna al repository	`docs/style/nextpdf-overrides.md` §5; `composer docs:jaccard-fingerprint`
Il fallback per le interruzioni è un protocollo reale	Interna al repository	La governance normativa del fallback RAG + il gate offline `docs:rag-fallback-check`

Esempio pratico

La disciplina è concreta: è la struttura del front-matter citations di una pagina. Ogni voce è la ricevuta tracciabile di un’affermazione.

citations:
  - spec: "ISO 32000-2"
    clause: "§6"
    # full 64-char reference ID — the join to the source span, re-verifiable
    reference_id: "<64-hex digest>"
    # NextPDF-worded topic — the paraphrase, never the standard's text
    topic: "A writer's created or amended PDF elements must conform and stay consistent"

Non esiste un campo quote, per scelta progettuale. Il topic è la riformulazione propria di NextPDF. Il reference_id è il modo in cui un revisore risale alla fonte esatta per verificare quella riformulazione. La ricevuta porta con sé il puntatore alla prova, non le parole della prova.

Equivoco comune

La trappola è leggere “parafrasa, non citare” come una scappatoia — un modo per apparire autorevoli senza impegnarsi. È il contrario. Una citazione non impegna a nulla; prende in prestito le parole di qualcun altro. Una parafrasi citata impegna chi scrive a una riformulazione che un revisore può confutare rispetto alla fonte. La disciplina rende le affermazioni più responsabili, non meno.

La seconda trappola è trattare “editoriale” come un livello più debole di “supportato da standard”. Non è un livello; è un tipo diverso. Una pagina editoriale come questa organizza e spiega altre evidenze. È etichettata correttamente. E l’etichetta è il punto: il sistema funziona perché una pagina indica che tipo di prova sta offrendo prima che si decida quanto peso darle.

Limiti e confini

Questa pagina specifica la disciplina delle citazioni; non è il foglio di stile, la governance del fallback né il codice del gate. Gli artefatti autorevoli sono interni al repository (docs/style/nextpdf-overrides.md §5, la governance normativa del fallback RAG, gli script composer.jsondocs:*) e, in caso di divergenza, prevalgono su qualsiasi riepilogo qui presente. Non afferma alcun comportamento del motore.

La disciplina vincola l’affermazione, non la conclusione del lettore. Una parafrasi citata fedelmente indica ciò che una clausola richiede. Stabilire se la lettura di NextPDF sia quella richiesta dal proprio obbligo resta una decisione dell’utente; per questo le pagine comportamentali portano anche evidenze supportate da codice o test, non solo da standard. L’applicazione è parziale per dichiarazione esplicita: il controllo offline del fallback è attivo, mentre i verificatori delle citazioni letterali e delle citazioni live sono collegati ai rispettivi runner esaustivi ancora in fase di completamento — dichiarato come in corso, non come fatto.

Documenti correlati

La documentazione come prodotto — la disciplina di qualità più ampia di cui questo sistema di citazioni fa parte.
Il panorama degli standard — gli standard a cui puntano queste citazioni e come una clausola diventa comportamento documentato.
La piramide dei test di NextPDF — cosa significa evidenza supportata da test quando una pagina dichiara quel livello invece di questo.

Glossario

Disciplina delle citazioni — l’insieme di regole che governa come un’affermazione di Insider_ è legata alla sua fonte: parafrasare, citare la clausola, ancorare un ID di riferimento, non citare mai uno standard soggetto a licenza.
Parafrasi — una riformulazione di un requisito con la voce propria di NextPDF, coerente con il glossario; il test di comprensione che sostituisce la citazione.
reference_id — il puntatore di integrità completo di 64 caratteri all’esatto intervallo della fonte da cui è stata tratta una parafrasi, registrato così che un revisore possa recuperarlo nuovamente e verificarlo.
Livello di evidenza — il tipo dichiarato di prova alla base delle affermazioni di una pagina, uno di otto (code-backed, standard-backed, test-backed, benchmark-backed, artifact-backed, design-principle, editorial, mixed), mostrato nella riga dei badge.
Citazione irrisolta — un’affermazione il cui ID di riferimento non è stato possibile ancorare a causa di un’effettiva interruzione del recupero; mantenuta, contrassegnata rispetto a un registro di ri-ancoraggio e trattenuta dalla pubblicazione anziché falsificata.