Il libro è pubblico perché il lavoro migliora quando qualcuno lo legge davvero. Le segnalazioni sono benvenute, e più sono precise, più diventano correzioni.
Leggendo il libro, seleziona la frase che non torna: compare un pulsante Segnala che apre una issue già compilata con la citazione, il link alla pagina con l'ancora della sezione e il file sorgente. Non devi cercare niente a mano.
In alternativa: apri una issue
scrivendo dove (capitolo e sezione), cosa c'è scritto e perché non
va. Per cose private, info@paithon.it.
Utile:
- errori di fatto, una data, un autore, un numero, un benchmark sbagliato;
- conti che non tornano, un esempio numerico che non si riproduce, una formula con un indice fuori posto, un pezzo di codice che non gira;
- passaggi poco chiari, se una spiegazione non ha funzionato su di te, è un dato: dire dove ti sei perso vale più di una riscrittura;
- link morti, refusi, figure che non caricano.
Meno utile, o da concordare prima in una issue:
- capitoli e sezioni nuove inviate come pull request senza averne parlato: l'indice segue un percorso, e ogni pagina deve rispettare regole editoriali vincolanti (vedi sotto). Meglio proporre l'idea e poi scriverla;
- riscritture stilistiche di testo corretto: la voce del libro è una scelta, non una svista;
- contenuti promozionali, link affiliati, tool da recensire.
Queste regole sono vincolanti. Le tre che contano più delle altre:
- Due livelli. Ogni concetto-chiave si spiega su Elementare e Superiore con le tab. L'Elementare deve superare il "test dell'ombrellone": comprensibile a uno studente di liceo, letto di fila.
- Ogni livello si regge da solo. Le tab non sono sincronizzate e il lettore ha un interruttore globale: qualcuno attraverserà tutto il libro senza vedere mai l'altro livello. Il Superiore non è l'Elementare con più formule, e l'Elementare non è il Superiore tagliato.
- Ogni affermazione fattuale è verificata su fonti primarie (paper,
documentazione ufficiale) e citata in
book/references.bib. Il codice Python va eseguito, non immaginato.
In pratica, scrivendo una pagina:
-
le tab si aprono con cinque backtick, sempre nell'ordine Elementare → Superiore, e avvolgono i passaggi dove la profondità cambia le cose (una definizione, una derivazione, una formula). Incipit, motivazione e transizioni stanno fuori e valgono per tutti i lettori:
`````{tab} Elementare Analogia concreta, zero prerequisiti. ````` `````{tab} Superiore Definizione formale, notazione, formule. `````
-
niente lineette (
—): non sono nello stile del libro. Un inciso che si potrebbe togliere va fra parentesi, un concetto racchiuso dentro la frase fra virgole, una spiegazione dopo i due punti, due proposizioni che si oppongono separate dal punto e virgola; per una digressione più lunga, una nota a piè di pagina ([^nota]). Restano il trattino d'unione e la lineetta breve degli intervalli (2020–2023). Vale per tutti e tre i modi di scriverla: il carattere lungo si vede scorrendo la pagina, le sue versioni in ASCII no, e sono quelle che scappano più facilmente. Quindi niente nemmenoparola -- parolanéparola - parola. Se hai dubbi,python3 scripts/coerenza.py --solo lineettete lo dice, e non segnala i segni meno delle formule né le opzioni da riga di comando; -
formule in LaTeX (
$…$in linea,$$…$$in blocco), con i simboli spiegati subito dopo. Notazione coerente col resto del libro, su tre livelli: matrici in maiuscolo grassetto ($\mathbf{X}$ ,$\mathbf{W}$ ), vettori in minuscolo grassetto ($\mathbf{x}$ ,$\mathbf{w}$ ), scalari e indici in minuscolo tondo ($x_i$ ,$n$ ); poi$\hat{y}$ per le predizioni,$\mathcal{L}$ per la loss,$\theta$ per i parametri. Il grassetto non è un vezzo tipografico: dice che l'oggetto ha più di una componente, e distingue un vettore da uno scalare; -
codice: Python idiomatico ed eseguibile, commenti in italiano e brevi. Il framework di deep learning del libro è PyTorch: niente Keras/TensorFlow, che possono comparire solo come citazione storica o confronto. Se una pagina ha un notebook in
notebooks/, il codice viene eseguito dalla CI: un blocco che non gira fa fallire la verifica. E se il testo commenta un numero, quel numero lo deve stampare il codice: un valore scritto a mano accanto a un blocco che non lo produce si scolla al primo ritocco, e chi legge esegue e non lo trova; -
figure: solo SVG geometriche in palette (terracotta
#B5532C, teal#2D5A5C, ocra#C9A961, warm-black#1A1A1A, cream#F8F5EE), leggibili anche in tema scuro. Niente immagini generate da AI, niente stock, niente gradienti. Se una figura non aggiunge comprensione, non serve; -
animazioni: dove il tempo è il contenuto (qualcosa che scorre, converge, si accumula, si propaga, si genera passo dopo passo) la figura può muoversi, e i generatori stanno in
animazioni/svg/, uno per figura. Regola vincolante: il disegno fermo è lo stato finale, con le coordinate vere e nessuna trasformazione, perché è quello che vedono la stampa, il PDF e chi ha chiesto al sistema di ridurre le animazioni; il movimento parte dall'inverso e finisce sull'identità. Solo@keyframesCSS, mai<script>. Se scrivi un capitolo nuovo, la domanda «qui il tempo è il contenuto?» va posta e risposta: se la risposta è no, si dichiara il capitolo inanimazioni/senza-clip.tomlscrivendo perché. Un capitolo a zero clip che non compare là fa fallire il controllo, e non per pignoleria: è già successo che nessuno se lo chiedesse per venticinque capitoli di fila; -
la firma visiva non si modifica da qui: colori, tipografia, sfondo animato, regole di stampa e lo stile delle figure animate vivono in
book/_static/brand, che è un submodule del design system condiviso col sito paithon.it. Una PR che ci scrive dentro, o che ne aggira un valore hard-codando un colore in_static/custom.css, non può essere accettata: vale solo per il libro e il sito resterebbe indietro. Se pensi che un token vada cambiato, aprine una issue e ne parliamo; -
ogni nuovo file va aggiunto a
book/_toc.yml, altrimenti non viene nemmeno costruito (only_build_toc_files: true). Il toc raggruppa i capitoli in parti (parts:concaption:, sono i blocchi dell'indice di sinistra): un capitolo nuovo va dentro la parte a cui appartiene. Ogni voce porta anche untitle:breve, è l'etichetta nell'indice, dove un titolo lungo andrebbe a capo due volte; il titolo esteso resta l'H1 della pagina. Un capitolo nuovo vuole anche la sua scheda nella griglia dibook/intro.md: il numero non si scrive (lo conta il CSS, lo<span class="pt-card-num">resta vuoto), epython3 scripts/coerenza.py --solo landingdice se una scheda manca o è fuori ordine. -
Quello che vale solo online va dichiarato. Il libro esiste in due formati: il sito e un PDF unico, che si scarica dalla home. Una frase come «in alto trovi il pulsante Esegui il codice» è vera sul sito e falsa su carta, quindi si avvolge:
:::{only} html In alto trovi il pulsante «Esegui il codice». ::: :::{only} latex Il codice di questo capitolo si esegue online, su book.paithon.it. :::Attenzione a come si annidano le recinzioni MyST: l'esterna deve essere più lunga dell'interna (
::::{only}che contiene:::{container}). Al contrario il blocco non si chiude dove sembra, e l'errore che ne esce parla d'altro.
Una cosa che il libro non ospita: la cronaca. Classifiche, benchmark, prezzi, "questo modello supera quell'altro" invecchiano dentro un testo che si legge per anni. Qui si spiega come funziona un meccanismo; le notizie stanno su paithon.it.
La correttezza è la soglia d'ingresso, non il traguardo: una pagina può essere tutta vera e restare illeggibile. Il traguardo è che uno se la legga di fila, senza fermarsi. Il metro è un buon articolo divulgativo, non una dispensa universitaria.
Queste cinque cose sono difetti, non questioni di gusto, e una revisione che ha riletto tutto il libro le ha trovate ovunque:
- il periodo lungo con tre subordinate, che regge la dimostrazione e uccide la lettura. Una idea per frase: se una frase ha due «che» e un «il quale», sono due frasi;
- il termine tecnico prima della cosa che nomina. Prima si dice cosa fa, poi come si chiama: «una rete che passa messaggi ai vicini, il message passing», non il contrario;
- l'attacco di sezione più difficile del resto della pagina. È il difetto numero uno del libro: chi legge il livello Elementare non ha ancora difese, e proprio lì gli si parla come al Superiore. Stessa cosa per le didascalie delle figure e i riquadri «Da ricordare», che spesso poggiano su un termine definito solo nella tab Superiore, cioè in un posto che quel lettore non aprirà mai;
- la parentetica che spezza il respiro dove il lettore stava prendendo il ritmo. Se l'inciso è lungo, è una frase dopo, o una nota;
- le citazioni infilate a metà periodo:
{cite}a fine frase, non fra soggetto e verbo.
E la soglia non è la stessa dappertutto: nei capitoli d'apertura (Introduzione, Python, Matematica, Machine Learning, Reti neurali, PyTorch, Deep Learning) arriva chi non ha basi, ed è lì che si decide se continuerà a leggere.
Se correggi, rileggi. Una correzione ne introduce di nuove più spesso di quanto sembri: rileggendo i capitoli corretti si sono trovati guasti creati dalla correzione stessa in sette casi su diciotto. Due accortezze che costano poco: cerca la tua correzione in tutte e due le tab (il libro dice ogni cosa due volte, e riparare solo il Superiore lascia l'errore dove fa più danno), e se rendi precisa una frase vaga apri prima la fonte, perché una frase precisa e sbagliata è peggio di una vaga e innocua.
Il libro è un Jupyter Book, costruito con la distribuzione TeachBooks (la stessa che usa il deploy). In locale:
pip install -r requirements.txt
teachbooks build book # equivale a `jupyter-book build book`
python -m http.server 8080 --directory book/_build/htmlNon è obbligatorio: la pubblicazione la fa GitHub Actions a ogni push su
book/. Se preferisci segnalare a parole, va benissimo: vedi sopra.
Il libro si scrive in un repository di lavoro privato e qui arriva pubblicato: è la ragione per cui la storia di questo repository è fatta di pubblicazioni e non di commit quotidiani. Per chi contribuisce cambia una cosa sola: la issue è la strada diretta, mentre una pull request accettata viene riportata a mano nel ramo di lavoro e torna qui con la pubblicazione successiva. Il commit che la porta online non è il tuo, ma ti cita come coautore: il credito segue la correzione.
Se ci vuole qualche giorno, non è disinteresse: è che una correzione entra quando il capitolo intorno regge ancora.
Ogni pubblicazione lascia una voce nella pagina Aggiornamenti del libro,
con il numero di versione, la data e il link alle pagine toccate: di lì si
vede quando una segnalazione è diventata una correzione online. Il registro è
book/_dati/aggiornamenti.yml e la pagina la scrive
python3 scripts/genera-aggiornamenti.py; una pull request non deve
aggiornarli, ci pensa chi pubblica.
Serve chiarirlo, perché i testi del libro sono sotto CC BY-NC-ND 4.0: una licenza che vieta le opere derivate. Un paragrafo corretto è tecnicamente un'opera derivata, quindi senza una concessione esplicita non potrebbe essere pubblicato nemmeno se la correzione fosse giusta.
Aprendo una issue o una pull request con del testo, delle figure o del codice, dichiari che:
- il contributo è opera tua, oppure hai il diritto di conferirlo (in particolare: non è copiato da libri, corsi o articoli di terzi);
- concedi a Francesco Messina / paithon.it una licenza non esclusiva, irrevocabile, gratuita e valida in tutto il mondo per pubblicarlo, modificarlo e distribuirlo come parte del libro, comprese le edizioni future, anche a stampa o commerciali;
- per il codice, il contributo si intende sotto Apache 2.0 come il resto del codice del progetto (è la regola di default della licenza stessa, §5), concessione di brevetto inclusa.
Resti autore di quello che hai scritto: la concessione è una licenza, non una cessione. Chi segnala un errore viene citato nel commit che lo corregge: la storia di git è il registro dei contributi.