Convenzioni di notazione, stile, glossario rapido

Un protocollo minimo: regole di lingua, notazione matematica, codice, figure, cross-reference. Tutto quello che serve per leggere la wiki con fluidita e scrivere un capitolo coerente.

Perché queste convenzioni

Un testo di trecento capitoli scritto senza convenzioni esplicite diventa ingovernabile. Ogni autore inventa la sua notazione matematica, ogni capitolo usa convenzioni di link diverse, ogni tabella ha uno stile suo. Il lettore deve imparare un sistema nuovo a ogni capitolo. Il manutentore non sa dove mettere le mani.

Le convenzioni sono un protocollo: riducono attrito per chi scrive e per chi legge, e permettono conversioni automatiche verso altri formati senza sorprese. Niente emoji, niente caratteri unicode decorativi, ASCII stretto fuori dalle formule: è quello che rende il sorgente portabile verso HTML, PDF, EPUB, Word template Amazon KDP.

Questo capitolo elenca le convenzioni in vigore. Non è una lista esaustiva — per il dettaglio operativo di chi scrive, la skill book-writing è la fonte autoritativa — ma copre tutto quello che il lettore ha bisogno di sapere per leggere con fluidita.

Lingua

La wiki è scritta in italiano corretto con diacritici. Forme accentate (è à ò ù ì é) usate dovunque l’ortografia le richieda: perché, può, così, più, già, città, qualità, è (verbo essere), né, sé, lì. Mai sostituire con ASCII (perche, puo, e', cosi): nessuna eccezione, nemmeno temporanea. Se l’editor su Windows mangia gli accenti, si cambia editor o si configura la tastiera. I drafts che hanno aggirato la regola in passato vanno bonificati prima della finalizzazione.

I termini tecnici in inglese restano in inglese: transformer, attention, tokenizer, embedding, harness, MoE, KV cache, prompt, fine-tuning, chain-of-thought. Non si traducono. Non si mettono in corsivo sistematicamente: sono parole del dominio. Chi lavora nell’AI parla così; la traduzione forzata (“trasformatore”, “autoregressivo incorporato”) suona accademica e distante dalla pratica.

I nomi propri di persone seguono una convenzione semplice: cognome alla prima menzione con anno quando rilevante, cognome solo dopo. Esempio: “Kahneman (2011) distingue Sistema 1 e Sistema 2… Kahneman sostiene che…”.

I nomi di paper si citano con titolo completo alla prima menzione. Dopo si usa il nome breve (es. “il paper di Chinchilla”, “il transformer originale”).

Notazione matematica

La matematica usa LaTeX inline con $...$ e block con $$...$$. È compatibile con Pandoc, MathJax, e la maggior parte dei renderer markdown tecnici.

Convenzioni standard sui simboli:

• Vettori minuscoli in grassetto: $\mathbf{x}, \mathbf{v}, \mathbf{q}, \mathbf{k}$.
• Matrici maiuscole corsive: $W, Q, K, V$.
• Scalari minuscoli normali: $x, y, \alpha, \beta$.
• Funzioni: $f(\cdot), \sigma(\cdot), \text{softmax}(\cdot)$, $\text{ReLU}(\cdot)$.
• Distribuzioni di probabilita: $p(x), q(y|x)$.
• Loss: $\mathcal{L}$, spesso con pedice esplicito: $\mathcal{L}_{\text{CE}}$, $\mathcal{L}_{\text{KL}}$.
• Attese: $\mathbb{E}[\cdot]$, con specifica della distribuzione a pedice se necessario: $\mathbb{E}_{x \sim p}[f(x)]$.
• Logaritmo naturale: $\log$ senza base quando non c’è ambiguita; $\log_2, \log_{10}$ altrimenti.
• Prodotto scalare: $\mathbf{a} \cdot \mathbf{b}$ o $\mathbf{a}^\top \mathbf{b}$, entrambe accettate.
• Norme: $\lVert \mathbf{x} \rVert_2$ con pedice esplicito.
• Gradiente: $\nabla_\theta \mathcal{L}$ rispetto ai parametri $\theta$.

Ogni simbolo introdotto va spiegato in prosa alla prima apparizione nel capitolo. Massimo una formula importante per paragrafo — se ne servono di più, il paragrafo va spezzato. Formule lunghe in display ($$), formule brevi inline.

Accanto a ogni formula non banale compare sempre una frase tipo “in parole povere, questo dice che…”: l’intuizione geometrica o operativa precede o accompagna il formalismo.

Codice

Il codice sta in blocchi triple-backtick con linguaggio specificato:

def attention(q, k, v):
    scores = q @ k.T / math.sqrt(d)
    weights = softmax(scores)
    return weights @ v

Linguaggi comuni: python, bash, json, yaml, typescript, rust, sql, pseudocode.

Si preferisce pseudocodice leggibile a codice runnable completo, a meno che l’esempio sia dichiaratamente pratico e debba funzionare. Le righe sono brevi (sotto 80 caratteri quando possibile, per impaginazione in PDF).

Gli identifier in codice restano in inglese, anche quando il resto del capitolo è in italiano: snake_case per Python, camelCase per JavaScript e TypeScript, PascalCase per tipi. Il codice è cross-culturale; rimescolare italiano e inglese nei nomi lo rende più difficile da leggere per chiunque.

I commenti nel codice spiegano il perché, non il cosa. Un commento tipo # incrementa i è rumore; # dopo questo punto la cache è invalidata è utile. Niente commenti decorativi, niente ASCII art.

Figure

Le figure non sono ancora generate. La wiki usa placeholder visibili su riga propria:

[FIGURA — breve descrizione di cosa mostra la figura]

Il placeholder è circondato da righe vuote. Il lettore del sorgente lo vede nel testo; il dev lo trova con ricerca; la conversione verso Word lo preserva come testo pieno, pronto per essere sostituito dall’immagine definitiva.

I prompt di generazione per le API di image gen (Gemini Image, gpt-image-1, Midjourney, DALL-E 3) si scrivono in un passaggio separato, in figures/<slug>/prompts.md, tramite il comando /figure-spec. Così la prosa del capitolo non resta ostaggio della generazione grafica.

La scelta di non includere le immagini nel sorgente markdown è esplicita: finché non esistono i file veri, ![alt](path) romperebbe il rendering. Meglio placeholder testuali che errori visivi.

Lo stile visivo di riferimento è technical-illustrated: palette sobria (bianco, nero, due-tre accenti colore semantici), tipografia sans-serif, metafore concrete quando aiutano. Il dettaglio vive nella skill book-figures.

Cross-reference

I rimandi ad altri capitoli usano link markdown relativi con path dentro chapters/:

`attention-intuizione` (in preparazione)

Mai usare numeri assoluti di capitolo nella prosa (“nel capitolo 5 vedremo…”): la numerazione può cambiare quando l’outline si riorganizza. Usare il titolo o lo slug: “vedi il capitolo su rope”.

I rimandi a documenti di progetto (outline, ENV, reading-paths) usano path relativi dalla directory chapters: ../outline.md, ../reading-paths.md, ../ENV.md.

I rimandi a un reading path specifico usano l’ancora: ../reading-paths.md#path-nome.

I rimandi a slug di un’altra Parte sono benvenuti: la wiki è un grafo, non un libro lineare. Non c’è un “troppo lontano” per un collegamento se il legame è vero.

I link a fonti esterne (paper, blog, docs) usano la sintassi markdown standard e aprono in nuova finestra quando la wiki diventerà sito. Nel sorgente è indifferente.

Marcatori editoriali

Tre marcatori in vigore, con significati precisi.

APPROFONDIRE — inline, in maiuscolo, dove un fatto non è stato verificato durante la stesura. Va accompagnato da una open-question in research/<slug>/open-questions.md. Nessun capitolo finale deve contenerne: un APPROFONDIRE residuo è un bug editoriale.

Check di avanzamento in outline:

• - [ ] non iniziato (cartella research/<slug>/ non esiste)
• - [~] in lavorazione (ricerca in corso o capitolo draftato ma non finale)
• - [x] finale (capitolo scritto + figure spec + revisione completata)

Open-questions:

• - [ ] domanda aperta
• - [x] risolta (seguita da una riga con la risposta sintetica)
• - [~] fuori-scope (seguita da motivazione esplicita)

Il marcatore [~] è non-standard nel markdown, ma reggibile e visivamente distinto. Funziona come stato intermedio senza richiedere un formato più elaborato (es. un file di metadati per slug).

Stile della prosa

Queste non sono convenzioni tecniche ma principi editoriali, validi per ogni capitolo.

Italiano corretto, paragrafi di 3-6 righe, frasi medie, voce attiva quando possibile. Niente frasi chilometriche: il lettore tecnico legge più in fretta di quanto ci si aspetti, ma si perde su subordinate multiple.

Il perché prima del come. Motivazione storica o operativa di un concetto, poi dettagli. Un concetto senza motivazione è una ricetta; con motivazione è comprensione.

Intuizione prima del formalismo, sempre. Una metafora concreta o un’analogia operativa prepara la formula. La formula senza metafora è ostile; la metafora senza formula è vaga.

Niente “in questo capitolo vedremo…” all’inizio di ogni sezione. È rumore. Il lettore vuole sapere, non vuole sapere di stare per sapere.

Niente riassunti didascalici a fine capitolo tipo “abbiamo visto X, Y, Z”. La sezione Collegamenti chiude il capitolo in modo più utile.

Niente marketing. Aggettivi tipo “potente”, “rivoluzionario”, “all’avanguardia” sono inutili. I fatti parlano.

Termini introdotti una volta. Se un capitolo definisce un termine, altri capitoli lo usano senza ridefinirlo. Il lettore è adulto: se ha dubbi, cerca.

Glossario rapido

Termini che la wiki usa dappertutto. Il glossario esteso vive nell’appendice app-glossario.

• Token: unita minima del tokenizer. Non necessariamente una parola. “hello world” potrebbe diventare 2-3 token a seconda del tokenizer.
• Embedding: rappresentazione vettoriale di un token o di un oggetto più grande (frase, documento, immagine).
• Context window: quantità massima di token che un modello può vedere in input. Varia da qualche migliaio (modelli vecchi) a milioni (modelli recenti).
• Prompt: input testuale al modello, inclusi istruzioni di sistema, contesto, domanda dell’utente.
• Completion: output generato dal modello.
• Inference: fase di generazione di output da un modello già addestrato. Opposto: training.
• Training: fase di apprendimento. Comprende pretraining (imparare la lingua/codice da corpus grande) + post-training (SFT, RLHF, ecc.).
• Fine-tuning: ulteriore training su un dataset specifico per adattare il modello a un task o dominio.
• Agente: sistema che osserva, decide e agisce in un loop, tipicamente usando tool esterni.
• Tool: funzione che un agente può chiamare (API, comando shell, lettura file, ricerca web, ecc.).
• Harness: runtime attorno al modello. Gestisce permessi, tool dispatch, memoria, hooks, sub-agenti, budget.
• MCP (Model Context Protocol): protocollo standard per connettere modelli a tool esterni e fonti di contesto.
• RAG (Retrieval-Augmented Generation): pattern che recupera informazioni rilevanti da un archivio e le inietta nel prompt.
• RLHF (Reinforcement Learning from Human Feedback): tecnica di post-training che usa preferenze umane come segnale.
• KV cache: memoria dei Key e Value già calcolati per token precedenti nella sequenza, per evitare di ricalcolarli.
• Temperature: parametro di sampling. Temperature bassa = output più deterministico; alta = più varietà.
• Top-k / top-p: tecniche di sampling che limitano i token candidati ai più probabili.
• Chain-of-thought (CoT): tecnica in cui il modello genera passi di ragionamento intermedi prima della risposta finale.
• In-context learning (ICL): capacità del modello di adattarsi a un task solo dagli esempi nel prompt, senza aggiornare i pesi.
• SFT (Supervised Fine-Tuning): fine-tuning con coppie input-output ideali etichettate da umani.
• Context engineering: disciplina del decidere cosa mettere nel context window e come.
• Prompt engineering: arte di scrivere prompt efficaci per ottenere il comportamento desiderato.
• Quantization: riduzione della precisione numerica dei pesi (es. da 32 bit a 4 bit) per ridurre memoria e velocizzare l’inferenza.
• LoRA: Low-Rank Adaptation, tecnica di fine-tuning parameter-efficient.
• Scaling laws: leggi empiriche che descrivono come loss, parametri, dati e compute si relazionano durante il training.

Come le convenzioni evolvono

Le convenzioni non sono scolpite nella pietra. Quando una scelta si rivela problematica, si cambia. Criteri per cambiare:

• Un numero sostanziale di capitoli ha lo stesso attrito.
• Una convenzione blocca una conversione verso un formato target (es. Word KDP).
• Una convenzione contraddice un’altra convenzione.
• L’ecosistema esterno cambia in modo che una certa scelta diventi non-standard.

Cambiare una convenzione implica riscrivere i capitoli già redatti per allinearli. Per questo, le modifiche vanno proposte in fase di outline, non a meta stesura. Le convenzioni di questo capitolo dovrebbero restare stabili per almeno una decina di capitoli consecutivi prima di essere riviste.

Le modifiche minori (aggiunta di un termine al glossario, precisazione di uno stile) non richiedono riscritture retroattive.

FAQ sulle convenzioni

“Perché niente emoji?” — Per portabilita. Emoji vengono rese in modo diverso da terminal, editor, viewer Word, stampanti. Alcune font mancano di emoji; alcune conversioni le perdono. Eliminarle da regola primaria risolve centinaia di piccoli problemi a valle.

“Perché LaTeX e non un altro sistema?” — Perché è lo standard de facto della comunità tecnica. Pandoc, Quarto, MathJax, KaTeX, Word (con MathType) lo supportano. Qualsiasi alternativa richiederebbe conversioni aggiuntive.

“Posso usare tabelle complesse?” — Tabelle semplici si. Tabelle con celle multi-riga, cell-spanning, nested tables no: sopravvivono male alla conversione. Quando la tabella si complica, meglio prosa strutturata o una figura.

“Posso definire nuovi marcatori?” — Meglio di no. Se senti che serve, proponilo in una nota di outline prima di usarlo in un capitolo.

“Se un paper usa notazione diversa, devo adattarla?” — Si, quando possibile. Riusare la notazione del paper nel testo della wiki crea incoerenza con altri capitoli. Se un’adattamento cambia la sostanza, segnalarlo esplicitamente.

Limiti

Queste convenzioni sono pragmatiche, non ottimali in senso assoluto. Sono pensate per un progetto singolo con un autore primario; un progetto multi-autore richiederebbe regole più stringenti (linter di stile, enforcement automatico). Un progetto solo-digitale potrebbe rilassare le regole anti-emoji o permettere rich widgets. Un progetto puramente accademico userebbe citazioni più pesanti (APA, IEEE).

Alcune scelte sono accettabili compromessi tra ideali contraddittori. Per esempio: vorremmo formule sempre eleganti, ma accettiamo LaTeX inline rudimentale quando il rendering finale è in Word. Sui diacritici invece il compromesso è stato eliminato: la regola è stretta in ogni fase, draft compreso.

Collegamenti

• intro-wiki — perché esiste la wiki, di cui queste convenzioni sono il protocollo operativo.
• percorsi-lettura — i reading path, che seguono queste convenzioni nella costruzione.
• mappa-concettuale — la vista d’insieme sul grafo della wiki.
• ../ENV.md — convenzioni operative e struttura del progetto.
• ../.claude/skills/book-writing/SKILL.md — skill di stile, la fonte autoritativa per chi scrive un capitolo.
• app-notazione (appendice) — notazione matematica completa con tutti i simboli adottati.
• app-glossario (appendice) — glossario esteso.