Disciplina delle citazioni

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

In sintesi

Questa è la pagina a cui rimanda il resto di Insider_ quando spiega come cita uno standard. Spiega perché questa documentazione parafrasa le specifiche invece di citarle, come un’affermazione indica lo standard e la clausola esatta su cui si fonda e che cosa, con precisione, una citazione pulita 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 collega a uno standard e a una clausola con nome. Quella citazione vale solo se la disciplina che la sostiene è esplicita. Se «supportato da standard» potesse significare qualunque cosa, da «ho letto la specifica con attenzione» a «ricordo grosso modo cosa diceva», la citazione 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 rintracciabile fino alla sua fonte senza riprodurre quella fonte. Una citazione precisa e una parafrasi fedele rispondono a entrambi i problemi, 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 e la clausola esatta; 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 indica una clausola o sezione specifica, non un intero documento, così che il revisore successivo possa aprire quella clausola e confermarvi la parafrasi.
Una citazione dichiara il tipo di fonte su cui si fonda — una clausola, il codice del motore, un test, una misurazione — così che un’affermazione eccessiva sia visibile a colpo d’occhio.
Quando un’affermazione non può essere legata a una clausola che chi scrive ha effettivamente letto, non viene falsificata. Viene mantenuta, contrassegnata come irrisolta, 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 e parafrasa il requisito con la propria voce.

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 indica la clausola, non solo il documento

Il meccanismo che rende verificabile una parafrasi è la precisione. Ogni affermazione supportata da standard indica la clausola o la sezione esatta su cui si fonda — per esempio ISO 32000-2 §6 — non il solo documento. Un revisore non deve fidarsi della memoria di chi scrive: apre quella clausola e la confronta con la riformulazione. Il riferimento alla clausola è il collegamento tra una fonte non citabile e un’affermazione verificabile. Indica dove guardare senza portare con sé il testo della fonte.

Una citazione indica di che tipo di fonte si tratta

Una citazione risponde a «da dove». Deve anche rispondere a «di che tipo». Dire che un’affermazione si fonda su una clausola di uno standard è una promessa diversa dal dire che si fonda sul codice del motore, su un test o su una misurazione. NextPDF tiene questi tipi distinti perché il lettore possa soppesarli: codice e test vengono prima del comportamento a runtime, il runtime prima dei metadati e i metadati prima della prosa. Una pagina editoriale come questa non finge di essere supportata dal codice.

Tipo di fonte	Cosa promette	Cosa non promette
Supportato dal codice	L’affermazione è verificata rispetto al sorgente del motore o a un esempio eseguibile	Che uno standard lo imponga
Supportato da standard	L’affermazione è ancorata a una clausola citata e parafrasata	Che il codice attualmente la implementi senza eccezioni
Supportato da test	Un test nella suite preserva quel comportamento	Una cifra prestazionale
Supportato da benchmark	Una misurazione secondo un metodo dichiarato supporta la cifra	La stessa cifra sul vostro hardware
Supportato da artefatto	Un artefatto prodotto (un output di build, un report) lo dimostra	Un mandato normativo
Principio di progettazione	Una decisione di progettazione deliberata e argomentata	Una misurazione empirica
Editoriale	Una spiegazione ragionata che organizza altro materiale	Una nuova garanzia comportamentale autonoma
Misto	La pagina combina più basi e indica quale vale per ciascuna affermazione	Una base unica e distinta

Questa pagina è editoriale: non afferma alcun comportamento proprio del motore. Spiega la disciplina su cui si basano le citazioni delle altre pagine. Questa è la sua base onesta, e dichiararlo significa applicare la disciplina a se stessa.

Quando la fonte non può essere letta

L’accesso a uno standard non è sempre immediato — una specifica soggetta a licenza può essere una che chi scrive deve ancora procurarsi, oppure una clausola può richiedere una seconda lettura perché il suo significato risulti chiaro. L’integrità della disciplina si vede in ciò che accade allora. Chi scrive non tira a indovinare. Un’affermazione che non può ancora essere legata a una clausola che chi scrive ha effettivamente letto viene mantenuta, collegata al materiale interno al repository e ai riferimenti normativi che il codice stesso dichiara, contrassegnata esplicitamente come irrisolta, e la pagina resta non pubblicata finché la clausola non è citata correttamente.

Le mosse proibite sono enumerate e verificabili: un numero di clausola inventato per apparire preciso, una citazione mascherata come se fosse stata letta quando invece è stata scritta a memoria, oppure la cancellazione silenziosa dell’affermazione per eludere la citazione. Una citazione aperta correttamente contrassegnata su una bozza è debito accompagnato da una nota, non un difetto. Un controllo offline e deterministico applica esattamente questa distinzione.

Esempio pratico

La disciplina è concreta: è la struttura del front-matter citations di una pagina. Ogni voce lega un’affermazione alla sua clausola.

citations:
  - spec: "ISO 32000-2"
    clause: "§6"
    # 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. spec e clause sono il modo in cui un revisore risale alla fonte esatta per verificare quella riformulazione. La voce porta con sé il puntatore alla clausola, non le parole della clausola.

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 clausola. 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 altro materiale. È etichettata correttamente. E l’etichetta è il punto: il sistema funziona perché una pagina indica su che tipo di fonte si fonda prima che si decida quanto peso darle.

Limiti e confini

Questa pagina specifica la disciplina delle citazioni; non è il foglio di stile né il codice del gate. Gli artefatti autorevoli sono interni al repository (docs/style/nextpdf-overrides.md §5 e 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 citazioni supportate da codice o test, non solo da standard. L’applicazione è parziale per dichiarazione esplicita: il controllo offline è 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 si fonda su quella base invece che su questa.

Glossario

Disciplina delle citazioni — l’insieme di regole che governa come un’affermazione di Insider_ è legata alla sua fonte: parafrasare, indicare la clausola esatta, 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.
Riferimento alla clausola — la clausola o la sezione esatta su cui si fonda una parafrasi, registrata così che un revisore possa aprirla e verificare la riformulazione.
Affermazione supportata da standard — un’affermazione ancorata a una clausola citata e parafrasata di uno standard con nome, a differenza di una supportata dal codice del motore, da un test, da una misurazione o da un ragionamento editoriale.
Citazione irrisolta — un’affermazione che non può ancora essere legata a una clausola che chi scrive ha letto; mantenuta, contrassegnata come aperta e trattenuta dalla pubblicazione anziché falsificata.