Guida di stile della documentazione

Questa guida definisce come viene scritta la documentazione EmDash. I contributi vengono modificati per conformarsi ad essa. Non è necessario memorizzarla — i revisori e gli editor aiuteranno — ma seguirla accelera la fusione di un contributo.

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

Leggibilità

Preferisci:

• Frasi brevi e paragrafi brevi.
• Vocabolario semplice anziché gergo.
• Abbreviazioni e acronimi scritti per esteso la prima volta.
• Intestazioni e liste per spezzare passaggi lunghi.
• Voce attiva.

Documenta come costruire con EmDash, non come EmDash è costruito. I dettagli implementativi appartengono alla documentazione solo quando cambiano una decisione che il lettore deve prendere (quando scegliere un valore non predefinito, un’avvertenza che influisce sul suo progetto). Non sostituiscono mai un esempio d’uso.

Per argomenti non EmDash — TypeScript, l’AT Protocol, web font, SQL — linka 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 della recenza di scrittura. Il fatto che una decisione sia nuova, o fresca nella mente dello scrittore, non è un motivo per evidenziarla. L’elemento più modificato è raramente il più importante per un lettore. Ordina sezioni, elementi di lista 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 documentazione.

• Rilevanza del costruttore sopra la rilevanza del lettore. L’architettura interna e le decisioni di design che erano significative da prendere sono generalmente 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 genuinamente qualcuno che lavora su EmDash, appartiene alla documentazione interna, 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 si dichiara X nel codice”). Descrivi ciò che EmDash fa, direttamente, e lascia che si sostenga da solo. Il confronto è permesso solo quando il confronto è la domanda del lettore stesso: nella pagina di valutazione e nelle pagine di orientamento “Venendo da…”. Anche lì deve essere specifico ed equo — comportamenti concreti e compromessi, non un uomo di paglia che il lettore è invitato a rifiutare.

• Definizione per negazione. Inquadrare una capacità come il lavoro che non devi fare — “nessuna migrazione da scrivere”, “nessun rebuild”, “senza toccare il codice”, “nessun servizio separato” — è un uomo di paglia mascherato: funziona solo per un lettore che porta l’alternativa che hai inventato per lui. Indica ciò che il lettore fa e ciò che accade. “Aggiungi un campo nel pannello di amministrazione; ha effetto immediatamente” — non “aggiungi un campo senza migrazione, senza rebuild, 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; “nessun rebuild necessario” è lo stesso fatto formulato come il dolore assente di qualcun altro — preferisci il primo.

Il test per qualsiasi frase: un lettore che cerca di completare il proprio compito starebbe peggio se fosse cancellata? Se no, cancellala. Se ha senso solo per un lettore che confronta EmDash con qualcos’altro, è nel posto sbagliato o dovrebbe essere tagliata.

Sempreverde, non changelog

Le pagine rivolte all’utente descrivono come EmDash funziona adesso, per un lettore che non ha nessuna versione precedente in testa. Nessun “adesso”, “non più”, “prima si”, “al posto del vecchio”, “questo è cambiato”. Le differenze versione per versione esistono solo in una guida di aggiornamento. Il fatto che un concetto sia stato introdotto di recente non è mai un motivo per menzionare che è recente.

Voce e tono

Scrivi frasi neutre e fattuali. Enuncia i fatti direttamente.

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

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

• Non usare noi, ci, nostro o facciamo. 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 dove qualcosa può andare storto.
• Non narrare o raccontare una storia. Nessun “ora che abbiamo configurato X, passiamo a Y”. Inizia una sezione con l’obiettivo, poi i passaggi.
• Evita stravaganze, 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 è l’<h1> (dal frontmatter title). Le sezioni iniziano con <h2>.
• Mantieni le intestazioni brevi. <h2> e <h3> appaiono nella barra laterale “In questa pagina”; visualizzale in anteprima e accorcia qualsiasi cosa che vada a capo.
• Nessuna punteggiatura finale, inclusi i due punti.
• Formatta il codice come <code> nelle intestazioni come nel corpo del testo.

Liste

• Usa un elenco puntato quando l’ordine non conta, come per 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 gli elementi della lista crescono in più paragrafi o portano diversi termini di codice, passa a sezioni <h3>.

Esempi

• “per esempio” per intero introduce un singolo esempio o ipotetico.
• “es.” tra parentesi introduce una lista non esaustiva (es. GitHub, GitLab).
• Una lista che copre ogni opzione non è una lista di esempi — usa parentesi senza “es.” (le proprietà richieste (src, alt)).

Screenshot

Usa uno screenshot solo quando chiarifica materialmente le relazioni spaziali, uno stato dell’interfaccia o la posizione dei controlli. Mantieni le istruzioni e altre informazioni essenziali nel testo in modo che la pagina rimanga utilizzabile senza l’immagine.

Ogni screenshot deve essere attuale e catturato per lo scopo specifico della pagina. Fornisci testo alternativo che descriva la schermata e lo stato pertinenti. Registra il fixture, la route, il viewport, il locale e il tema in modo che un altro contributore possa riprodurre la cattura.

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 su una riga propria, 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, così deve solo capire come. Crea anche un pattern a riempimento 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 una.

• 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 le annotazioni Expressive Code, non fence ```diff grezze, per le modifiche prima/dopo. Segna le righe cambiate con del={n} / ins={n} o il testo cambiato con del="…" / ins="…". Mantieni i diff minimali e locali alle righe che cambiano.

  L’esempio seguente mostra un cambio di una singola riga:

  ```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 devo fare?” sono la parte che i lettori apprezzano di più — non lesinarci sopra.

Apri con: come aggiornare, una nota che le cose potrebbero “funzionare” ma di continuare a leggere in caso contrario, e un link al changelog.

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

### [Rinominato/Modificato/Rimosso/Deprecato]: <funzionalità>

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

<Una frase, presente, come funziona ora>.

#### Cosa devo fare?

<Azioni imperative: Aggiornare… / Sostituire… / Rimuovere…, con un diff minimale.>

Scegli il verbo in base a come il lettore percepisce l’impatto. Se un nuovo valore predefinito sostituisce il suo valore, è un “Modificato: valore predefinito”, non un “Aggiunto: opzione”.

Una modifica che rompe la compatibilità è una che richiede un cambiamento nel progetto del lettore altrimenti 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”.

Specifiche EmDash

Convenzioni per situazioni ricorrenti, ordinate per la frequenza con cui un contributore le incontra. Questa è una lista di convenzioni, non una classifica di quali funzionalità contano di più.

Plugin: sandboxed vs nativi

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

Localizzazione

Non includere modifiche a messages.po in un PR di documentazione. Un workflow estrae i cataloghi al merge in main. Includerli crea churn 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 snella, segnalala con un <Aside> di attenzione e punta all’RFC o alla discussione come fonte di verità. Non documentare una superficie instabile in dettaglio esaustivo.

Account Atmosphere

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

La documentazione è 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; un cambio di formulazione può spostare il significato di una frase o necessitare di modifiche corrispondenti altrove nel sito. Modifiche piccole, revisionate e coerenti mantengono l’intero sito coerente.