Convenzioni di stile e contenuto

Gli appunti devono essere chiari, concisi ma completi. L’obiettivo è creare la bibbia del corso: idealmente studiandola da zero si dovrebbe arrivare al 30L.

In tale prospettiva proponiamo una guida alle fasi di integrazione e di review che chiarifichi che cosa dev’essere presente negli appunti e lo stile di scrittura consigliato.

Naturalmente, queste indicazioni valgono per gli appunti proposti per il branch master: per gli appunti presi a lezione è assolutamente OK essere vaghi o brevi.

Guida all’integrazione

La fase di integrazione degli appunti dovrebbe servire per riunire gli appunti di tutti i partecipanti in un unico documento. Per agevolare la fase di review e riscrittura, tuttavia, questo non può limitarsi a un semplice merge dei rispettivi file: l’integratore ha il compito di fornire a colui che dovrà riscrivere gli appunti la miglior base possibile su cui lavorare.
Ecco dunque alcuni consigli utili in tal senso:

  • Assicurarsi che CI SIA TUTTO: idealmente la fase di review dovrebbe solo fare “refactoring” degli appunti senza aggiungere nessun concetto, per cui è espressa responsabilità dell’integratore assicurarsi che il risultato finale sia assolutamente completo in quanto nessuno controllerà più i contenuti.

  • Una frase, una riga: al termine di ciascuna frase (ndr. una proposizione terminata da punto) andare a capo in Markdown. Questo infatti non spezza il paragrafo, come si può vedere dalla preview, ma agevola moltissimo il versioning con Git in quanto ogni frase viene così trattata come una linea di codice indipendente dalle altre.

  • Assicurarsi che le stesse cose non siano dette in più punti diversi e, nel caso, integrarle tra di loro;

  • Tenere i propri appunti sottomano per accertarsi che ogni concetto citato a lezione sia riportato: è chiaro che all’esame viene chiesto tutto, compresi i riferimenti esterni, per cui occorre includere negli appunti ogni nozione rilevante;

  • Organizzare gli argomenti in maniera logica, evitando salti logici in avanti e in indietro per agevolare il lavoro di review;

  • Sfruttare le potenzialità di Markdown (es. titoli di vario livello, tabelle, elenchi…) e rispettarne per quanto possibile le convenzioni (es. linea vuota dopo i titoli, nessuno spazio alla fine di una riga…);

  • Tenere sempre la preview di mdbook aperta per verificare che immagini e/o schemi vengano mostrati correttamente.

Guida alla review

Gli appunti definitivi dovrebbero costituire un discorso omogeneo e fluido, come fossero un piccolo libro di testo.
Per fare ciò, ecco alcune accortezze di stile e consigli utili durante la fase di review e riscrittura: si tratta solo di indicazioni (“Just rules” ^-^), per cui non sentitevi in dovere di seguirle alla lettera.

Contenuto

  • Immaginare sempre di stare parlando con chi non sa nulla della materia: leggendo gli appunti dall’inizio alla fine si dovrebbe essere in grado di comprendere tutto. È quindi importante:

    • non citare concetti senza che siano stati già spiegati precedentemente: se invece sono già stati spiegati può essere utile richiamarli con una formula del tipo “Come sappiamo…” o “Come abbiamo già visto…” seguita da un breve accenno al concetto;

    • non dare per scontato nessuna conoscenza;

  • Se qualcosa è preso pari pari dalle slide può essere un campanello d’allarme. Conviene dunque farsi le seguenti domande:

    • La frase si sposa bene con lo stile del discorso? Come potrei riscriverla in modo da rendere il fluire del discorso più omogeneo?

    • Il concetto espresso non è affrontato da nessun’altra parte? Se sì, tale ripetizione è davvero necessaria e funzionale?

  • Mantenere convenzione “una frase, una riga” adottata nella fase di integrazione (vd. sopra): specialmente nella fase di review è importante che modificare una singola frase non comporti modificare interi paragrafi.

  • Tenere i propri appunti sottomano per verificare ulteriormente che non manchi nulla: sebbene la fase di integrazione dovrebbe in teoria creare un documento completo di tutto, può capitare che qualcosa sia sfuggito.

Stile

  • Adottare una sintassi semplice: gli appunti dovrebbero essere completi ma facili da seguire;

  • Avere una qualche estensione di controllo ortografico attiva (es. Code Spell per vscode);

  • Usare il più possibile l’impersonale: non “possiamo fare X” ma “si può fare X”;

  • Sforzarsi di presentare gli argomenti nel modo più chiaro possibile, legandoli tra di loro in unico discorso logico. Per favorire questo approccio, ogni argomento dovrebbe essere affrontato nel modo seguente:

    1. Presentare il problema: es. “Spesso capita di dover gestire X, Y e Z”;

    2. Discutere e analizzare il problema: es. “Il problema ha queste queste e queste caratteristiche, che non possiamo risolvere con quanto visto finora”;

    3. Proporre la/le soluzione/i al problema e discuterle, confrontandole se più di una: es. “In un primo momento si potrebbe pensare di risolvere così; tuttavia questo approccio ha questi difetti. Ecco allora che si è pensato di fare quest’altro”;

    4. Concludere con un breve riassunto su quanto visto, che servirà inoltre a introdurre il prossimo argomento: es. “Abbiamo quindi visto come risolvere sta cosa; la soluzione pone però un nuovo problema…”.

  • Preferire i discorsi omogenei agli elenchi: usare gli elenchi SOLO quando necessari. Alcuni esempi dei pochi casi in cui un elenco è accettabile sono:

    • un elenco puntato quando si elencano più cose contrapposte tra di loro (es. diversi approcci o soluzioni a un problema)

    • un elenco numerato quando si specificano le varie fasi di un processo (es. ciclo di vita del software)

  • Utilizzare la separazione in paragrafi in modo coscienzioso: all’interno di un paragrafo dovrebbe idealmente essere trattato un unico concetto. Diversi aspetti dello stesso concetto possono essere separati nello stesso paragrafo andando a capo (con \ al termine della riga), mentre quando si passa al concetto successivo è bene aprire un nuovo paragrafo.

  • Utilizzare la corretta punteggiatura. Può essere utile in tal senso rileggere mentalmente gli appunti appena scritti per assicurarsi che il discorso fluisca in modo scorrevole, ricordando che:

    • la virgola (“,”) rappresenta una pausa brevissima utilizzata per riprendere fiato o per evidenziare tramite un inciso (una frase compresa tra due virgole) determinati concetti che espandono in modo significativo il discorso principale;

    • i due punti (“:”) rappresentano una pausa breve e sono usati per introdurre elenchi o proposizioni strettamente correlate con quella principale;

    • il punto e virgola (“;”) rappresentano una pausa media, e vanno utilizzati quando si vuole dare un legame debole alla proposizione con la precedente e al termine di ogni elemento di un elenco tranne l’ultimo (dove invece si usa il punto);

    • le parentesi (“(…)”) vengono utilizzate per incapsulare proposizioni che espandono la frase principale in modo non significativo: idealmente esse potrebbero essere saltate nella lettura senza togliere nulla al discorso.

  • Utilizzare il grassetto per evidenziare concetti chiave e il corsivo per sottolineare frasi importanti; all’interno delle parentesi si può inoltre utilizzare il corsivo per aumentare la rilevanza del contenuto.

  • Usare le congiunzioni correttamente per legare le frasi tra di loro (es. dunque, perché, perciò, allora, in quanto…);

  • NON IGNORARE I COMMENTI: si tratta di richieste di aiuto da parte di chi ha fatto l’integrazione, che chiede un consiglio su una determinata questione. È dunque importante che per il termine della review tale problema sia stato risolto: se vi trovate in difficoltà potete sempre chiedere sul gruppo!