Com'è strutturata la documentazione di NextPDF

In breve

Il manuale di NextPDF si sviluppa secondo un contratto fisso. Ogni pagina ha un solo argomento, una sola modalità Diataxis e un solo tipo di pagina. Ogni tipo di pagina ha un insieme obbligatorio di intestazioni di livello 2. Un numero limitato di manifest e gate mantiene coerente la struttura man mano che il manuale si espande.

Questa pagina descrive la forma di questo sistema, affinché il contributo arrivi nel posto giusto. Il contratto completo e normativo, incluse le liste esatte delle intestazioni, le regole di citazione e la procedura passo passo di integrazione nei gate, è contenuto nel documento di governance interno docs/style/expansion-standard.md. Leggere prima questa pagina; consultare quel documento durante la redazione.

Scelta di un tipo di pagina

Seguire questa regola, nell’ordine indicato, per decidere se aggiungere una pagina o estenderne una esistente:

1. Se il materiale costituisce un argomento distinto che un lettore non si aspetterebbe nella pagina esistente, aggiungere una nuova pagina.
2. Se il materiale completa un argomento già coperto dalla pagina esistente, estendere tale pagina.
3. Se il materiale è un dettaglio approfondito che appesantirebbe una pagina di installazione, avvio rapido o attività, spostarlo in una pagina separata e collegarlo.
4. In caso contrario, estendere la pagina esistente.

Una volta stabilita l’esistenza della pagina, impostarne la modalità Diataxis, che determina il tipo di pagina:

• Un tutorial istruisce chi apprende, quindi usare una guida alle attività scritta come una ricetta.
• Una guida pratica aiuta un lettore competente a portare a termine un’attività, quindi usare una guida alle attività, una guida alle API del server o una guida all’SDK.
• Un riferimento riporta fatti precisi, quindi usare un riferimento API o una pagina indice.
• Una spiegazione favorisce la comprensione, quindi usare una guida per sviluppatori o una guida alle funzionalità premium.

Il linguaggio chiaro è la base in ogni modalità, non una modalità a sé stante.

Il catalogo dei tipi di pagina

Il contratto del manuale riconosce i tipi seguenti. Riutilizzare un tipo esistente ogni volta che la pagina contiene una tabella API; introdurre un nuovo tipo solo come etichetta, e soltanto per una pagina priva di tabella API.

• Tipi indice: section-index, api-index, extension-index.
• Tipo di riferimento: api-reference. Riutilizzarlo per qualsiasi pagina con la tabella API standard, inclusi i riferimenti del server e dell’SDK Python.
• Tipo di spiegazione: developer-guide. Riutilizzarlo per i testi su architettura, ciclo di vita e punti di estensione, incluse le guide del server e dell’SDK Python.
• Nuovi tipi solo come etichette: premium-feature-guide e task-guide, entrambi per pagine prive di tabella API.

Ogni pagina si apre con ## At a glance. Ogni pagina api-reference contiene la tabella API condivisa e l’intestazione Development notes. Le intestazioni obbligatorie sono esattamente di livello 2, ciascuna su una riga propria; è possibile aggiungere altre intestazioni al di sotto di esse.

Lista di controllo per la redazione

Durante la scrittura di una pagina, soddisfare entrambe queste liste di controllo. Lo standard interno enuncia ciascun elemento in modo normativo e rimanda allo standard su cui si basa.

Facilità d’uso per gli sviluppatori:

• Ricavare gli esempi eseguibili da examples/ o tests/Cookbook e associare a ciascun blocco delimitato una stringa informativa title=.
• Indicare i prerequisiti nel front matter e nell’introduzione.
• Mostrare l’output previsto per ogni esempio che ne produce uno.
• Mantenere i blocchi pronti per copia e incolla: un solo linguaggio per blocco, nomi completi al primo utilizzo, nessun carattere di prompt finale.
• Mostrare codice sicuro per impostazione predefinita: gli esempi di produzione usano try/catch con l’eccezione NextPDF più specifica e non contengono mai un catch vuoto.
• Concludere con i collegamenti di approfondimento e impostare related: nel front matter.

Predisposizione alla traduzione:

• Esprimere un’idea per frase, affinché la traduzione automatica non produca frasi prolisse.
• Mantenere brevi le intestazioni e le etichette, perché la maggior parte delle lingue di destinazione si espande.
• Evitare le espressioni idiomatiche.
• Mantenere in formattazione di codice i nomi dei simboli, le chiavi di configurazione, i flag della CLI e i nomi delle eccezioni; i nomi degli standard come PDF/A-4, PAdES ed eIDAS non si traducono mai.
• Impostare in modo accurato i18n_ready e xliff_segments e scrivere in Unicode NFC.

Per tono, esempi di codice, terminologia e stile delle citazioni, seguire il foglio ratificato di override dello stile a cui rimanda lo standard interno.

Integrazione nei gate

L’integrazione di una nuova pagina segue una procedura ordinata:

1. Creare la struttura della pagina in modo che il suo front matter corrisponda allo schema del sito.
2. Redigere il corpo in base alle intestazioni obbligatorie del tipo di pagina.
3. Aggiungere una voce { path, owner, kind, headings[] } a docs/manual-contract.json. Il percorso è relativo a src/content/docs, usa barre in avanti e non riporta né una barra iniziale né ...
4. Per un riferimento API, aggiungere i simboli della pagina a docs/api-coverage-manifest.json; ogni simbolo deve comparire nella pagina ed esistere nel codice sorgente.
5. Aggiornare docs/source-manifest.json solo quando la pagina proviene da un nuovo repository di origine.
6. Aggiungere la pagina al gruppo della barra laterale corretto in astro.config.mjs come voce esplicita.
7. Aggiungere una riga di copertura delle impostazioni locali con tutte le diciassette celle delle impostazioni locali impostate su missing per una pagina disponibile solo in inglese.
8. Eseguire i gate della documentazione, la build e il budget delle prestazioni.

Le pagine di proprietà del sito risiedono in src/content/docs, impostano owner su nextpdf-docs e non riportano mai un marcatore di aggregazione. Le pagine aggregate provengono da un repository di origine e il relativo flag di pubblicazione risiede nel front matter di origine, quindi si modificano lì, non qui.

Vedere anche

• Integrazioni: l’esempio applicato più esteso della forma del manuale attraverso numerosi pacchetti.
• Il documento di governance interno docs/style/expansion-standard.md contiene il contratto completo: liste esatte delle intestazioni per ogni tipo di pagina, le regole di citazione e la procedura completa di integrazione nei gate.