Guida allo Stile della Documentazione

Questa guida definisce come viene scritta la documentazione di EmDash. I contributi vengono modificati per corrispondere. Non è necessario memorizzarla — i revisori e gli editori aiuteranno — ma seguirla fa sì che un contributo venga unito più velocemente.

La documentazione esiste per aiutare qualcuno a fare qualcosa e poi tornare al proprio progetto. Scrivi per un lettore che è stanco, ha fretta, legge in una seconda lingua o è nuovo allo stack. Servi quel lettore sopra ogni altra cosa.

Leggibilità

Preferisci:

Frasi brevi e paragrafi brevi.
Vocabolario semplice invece di gergo.
Abbreviazioni e acronimi scritti per esteso la prima volta.
Intestazioni e elenchi per suddividere passaggi lunghi.
Voce attiva.

Documenta come costruire con EmDash, non come è costruito EmDash. I dettagli di implementazione appartengono ai documenti solo quando cambiano una decisione che il lettore deve prendere (quando scegliere un valore non predefinito, un avvertimento che influisce sul loro progetto). Non sostituiscono mai un esempio d’uso.

Per argomenti non-EmDash — TypeScript, il protocollo AT, i font web, SQL — collega a una fonte affidabile invece di spiegarli. Documenta ciò che qualcuno deve sapere per usare la funzionalità in EmDash.

Cosa enfatizzare

L’enfasi di una pagina deve essere determinata da ciò di cui il lettore ha bisogno per svolgere il proprio compito, mai da ciò che era interessante o recente per le persone che hanno costruito EmDash. Tre abitudini a cui resistere attivamente:

Peso dell’autore per recenza. Il fatto che una decisione sia nuova o fresca nella mente dello scrittore non è una ragione per metterla in evidenza. La cosa più cambiata è raramente la cosa più importante per un lettore. Ordina sezioni, voci di elenco e titoli in base alla frequenza con cui un lettore ne ha bisogno, non in base a quando sono stati aggiunti. Se stai documentando qualcosa perché è appena cambiato, probabilmente stai scrivendo una voce di changelog, non un documento.
Prominenza del costruttore sopra prominenza del lettore. Le decisioni di architettura e design interne che erano significative da prendere sono solitamente invisibili e irrilevanti da usare. Indica la capacità che il lettore ottiene, non il meccanismo dietro di essa. Un lettore che definisce una collezione non ha bisogno di sapere dove è memorizzato lo schema, così come non ha bisogno di conoscere il linguaggio del parser. Se il meccanismo aiuta davvero qualcuno che lavora su EmDash, appartiene al documento internals, non a una pagina rivolta all’utente.
Auto-definizione per uomo di paglia. Non definire EmDash per contrasto con una caricatura di altri strumenti (“A differenza della maggior parte dei CMS…”, “I CMS tradizionali ti costringono a…”, “in molti CMS dichiari X nel codice”). Descrivi cosa fa EmDash, direttamente, e lascia che si distingua da solo. Il confronto è consentito solo quando il confronto è la propria domanda del lettore: sulla pagina di valutazione e le pagine di orientamento “Venendo da…”. Anche lì deve essere specifico e giusto — comportamenti e compromessi concreti, non un uomo di paglia che il lettore è invitato a non gradire.
Definizione per negazione. Inquadrare una capacità come il lavoro che non devi fare — “nessuna migrazione da scrivere”, “nessuna ricostruzione”, “senza toccare il codice”, “nessun servizio separato” — è un uomo di paglia mascherato: funziona solo per un lettore che sta portando l’alternativa che hai inventato per loro. Indica cosa fa il lettore e cosa succede. “Aggiungi un campo nel pannello di amministrazione; ha effetto immediatamente” — non “aggiungi un campo senza migrazione, senza ricostruzione, senza codice”. L’eccezione è un comportamento concreto rilevante per il lettore espresso positivamente: “il contenuto viene servito a runtime, quindi le modifiche appaiono immediatamente” è un fatto su EmDash; “nessuna ricostruzione necessaria” è lo stesso fatto formulato come dolore assente di qualcun altro — preferisci il primo.

Il test per qualsiasi frase: un lettore che cerca di finire il proprio compito starebbe peggio se fosse eliminata? In caso contrario, eliminala. Se ha senso solo per un lettore che confronta EmDash con qualcos’altro, è nel posto sbagliato o dovrebbe essere tagliata.

Sempre attuale, non changelog

Le pagine rivolte agli utenti descrivono come funziona EmDash ora, per un lettore che non ha una versione precedente in testa. Niente “ora”, “non più”, “usato”, “invece del vecchio”, “questo è cambiato”. Le differenze da versione a versione vivono solo in una guida di aggiornamento. Il fatto che un concetto sia stato introdotto di recente non è mai una ragione per menzionare che è recente.

Voce e tono

Scrivi frasi neutre e fattuali. Indica i fatti direttamente.

✅ I plugin vengono eseguiti in un runtime isolato e possono raggiungere solo le API che dichiarano.

❌ I plugin vivono in una piccola sandbox accogliente dove non può mai succedere nulla di male!

Non usare noi, ci, nostro o andiamo. Non sei seduto con il lettore. Riformula per rivolgerti direttamente al lettore o descrivere il sistema.
Non usare mai io. La documentazione non riguarda l’autore.
Rivolgiti al lettore come tu quando necessario, specialmente per segnalare un passaggio in cui qualcosa può andare storto.
Non narrare né raccontare una storia. Niente “ora che abbiamo configurato X, passiamo a Y”. Inizia una sezione con l’obiettivo, poi i passaggi.
Evita bizzarrie, mascotte e riferimenti culturali. Aggiungono sforzo di lettura e non si traducono.
I punti esclamativi sono rari. Usane uno solo per qualcosa di genuinamente incoraggiante o sorprendente. In caso di dubbio, usa un punto.

Intestazioni

Il titolo della pagina è il <h1> (dal frontmatter title). Le sezioni iniziano a <h2>.
Mantieni le intestazioni brevi. <h2> e <h3> appaiono nella barra laterale “In questa pagina”; visualizzalo in anteprima e accorcia tutto ciò che va a capo.
Nessuna punteggiatura finale, inclusi i due punti.
Formatta il codice come <code> nelle intestazioni allo stesso modo che nel testo del corpo.

Elenchi

Usa un elenco puntato quando l’ordine non ha importanza, come un insieme di opzioni o proprietà.
Usa un elenco numerato per passaggi che devono essere seguiti in sequenza. Usa il componente <Steps> di Starlight per le procedure.
Quando le voci dell’elenco crescono in più paragrafi o portano diversi termini di codice, passa invece alle sezioni <h3>.

Esempi

“ad esempio” per esteso introduce un singolo esempio o ipotetico.
“es.” tra parentesi introduce un elenco non esaustivo (es. GitHub, GitLab).
Un elenco che copre ogni opzione non è un elenco di esempi — usa parentesi senza “es.” (le proprietà richieste (src, alt)).

Esempi di codice

Gli esempi di codice sono importanti quanto la prosa che li circonda.

Introduci ogni blocco di codice con una frase completa e autonoma sulla propria riga, dicendo al lettore cosa fa il blocco. Non iniziare con un frammento di frase che termina con due punti, un’intestazione nuda o “così:”.

✅ L’esempio seguente registra un plugin nell’array sandboxed:

❌ Aggiungi il plugin così:

L’introduzione prepara il lettore a cosa fa il codice, quindi deve solo capire come. Crea anche un modello di riempimento degli spazi vuoti per un lettore che fa qualcosa di leggermente diverso.

All’interno di una procedura <Steps>, un’istruzione imperativa diretta è l’introduzione (“Aggiungi un tsconfig.json:” seguito dal file va bene in un passaggio numerato).

Altre regole:

Usa codice reale e funzionante. Niente foo/bar. Mostra una configurazione realistica, non ogni valore possibile — il lettore ne avrà solo uno.
Aggiungi un nome file title= a qualsiasi blocco che rappresenta un file, in modo che il lettore sappia dove va il codice.
```
```ts title="src/plugin.ts"
```
Usa annotazioni Expressive Code, non recinzioni ```diff grezze, per modifiche prima/dopo. Segna righe modificate con del={n} / ins={n} o testo modificato con del="…" / ins="…". Mantieni i diff minimali e locali alle righe che cambiano.

L’esempio seguente mostra una singola riga che cambia:
```
```ts del={1} ins={2}
import { definePlugin } from "emdash";
import type { SandboxedPlugin } from "emdash/plugin";
```
```
Visualizza in anteprima il codice renderizzato localmente prima di inviare. Un errore di battitura può rompere la visualizzazione.

Guide di aggiornamento e migrazione

Una guida che aiuta un lettore a spostare un progetto esistente a una nuova versione segue una struttura fissa. Le sezioni “Cosa dovrei fare?” sono la parte che i lettori apprezzano di più — non lesinare su di esse.

Apri con: come aggiornare, una nota che le cose possono “semplicemente funzionare” ma continua a leggere se non lo fanno, e un link al changelog.

Poi elenca ogni modifica che rompe la compatibilità come voce propria:

### [Renamed/Changed/Removed/Deprecated]: <feature>

Nelle versioni precedenti, <una frase, tempo passato, cosa faceva>.

<Una frase, tempo presente, come funziona ora>.

#### Cosa dovrei fare?

<Azioni imperative: Aggiorna… / Sostituisci… / Rimuovi…, con un diff minimo.>

Scegli il verbo in base a come il lettore sente l’impatto. Se un nuovo valore predefinito sostituisce il loro valore, è un “Changed: default value”, non un “Added: option”.

Una modifica che rompe la compatibilità è una che richiede una modifica al progetto del lettore o smette di funzionare. Dai l’azione, non solo il fatto. Non “la versione minima di Node.js è ora X” ma “controlla la tua versione di Node.js con il seguente comando e aggiorna se è inferiore a X”.

Specificità EmDash

Convenzioni per situazioni ricorrenti, ordinate per frequenza con cui un contributore le incontra. Questo è un elenco di convenzioni, non una classifica di quali funzionalità contano.

Plugin: sandboxed vs native

I plugin sandboxed e native sono formati diversi con forme di authoring diverse. Una modifica a uno raramente influisce sull’altro. Indica di quale formato parla una pagina o un esempio. Quando modifichi una pagina di plugin sandboxed, non modificare esempi di plugin native, e viceversa.

Localizzazione

Non includere modifiche a messages.po in un PR di documentazione. Un workflow estrae i cataloghi al merge su main. Includerli crea agitazione e conflitti di merge.

Funzionalità sperimentali

Una funzionalità dietro un flag sperimentale, o un formato wire instabile sotto un RFC, può cambiare senza preavviso. Mantieni la sua documentazione leggera, contrassegnala con un <Aside> di cautela e indica l’RFC o la discussione come fonte di verità. Non documentare una superficie instabile nei minimi dettagli.

Account Atmosphere

Quando l’identità portatile e di proprietà dell’utente dietro Bluesky e la rete AT Protocol più ampia viene fuori, chiamala un account Atmosphere e usa quel termine in modo coerente. Collega la prima menzione alla guida di accesso Atmosphere o atmosphereaccount.com. did:plc:… e gli handle sono i suoi identificatori concreti; usali dove è necessario un valore letterale.

I documenti sono codice

Il sito di documentazione è un progetto Astro adiacente a EmDash. Le modifiche alla documentazione passano attraverso lo stesso flusso di pull request e revisione del codice. Ogni modifica al testo attende una revisione; una modifica di formulazione può spostare il significato di una frase o richiedere modifiche corrispondenti altrove sul sito. Modifiche piccole, riviste e coerenti mantengono l’intero sito coerente.