Guida per contributors

SoftPython vuole essere un libro per umani, quindi:

Dare del tu al lettore, quindi preferire scrivi a scrivete
Quando possibile inventare storielle, variando i temi (pirati, cowboy, etc), aumentano incredibilmente l'attenzione e partecipazione degli studenti
Ogni concetto presentato dovrebbe essere seguito da un qualche esercizio e/o domande
Usare nomi in italiano per le variabili, evitare nomi astratti tipo x, per es monete è molto meglio
Se si ha voglia, fare disegni / schemi in SVG con Inkscape ed esportarli in png (fornire entrambi). Metterli in sottocartelle img/. Se si prendono immagini dal web, ACCERTARSI che la licenza permetta il riuso (idealmente CC0 o CC-BY) e ringraziare nel testo l'autore.
Per ogni comando che si usa, accertarsi sempre che sia stato definito precedentemente nel libro. Tenere ridotto il numero di metodi diversi da usare negli esercizi
indicare sempre chiaramente le supposizioni fatte (es: lista di lunghezza fissa 4...)

Nei primi fogli dei fondamenti (1,2,3..):

non usare iterazione, definizione di funzioni, assert
deve essere sempre chiaro se del codice produce un risultato (eventualmente da stampare) oppure MODIFICA l'input.
usare la locuzione 'Scrivi del codice che'
quando possibile mettere gli input su una sola linea seguiti dal risultato atteso commentato, aggiungendo almeno un'altro caso di test commentato tipo:

vel,km = 23,48    # True
# vel,km = 15,39  # False
# vel,km = 22,50  # False

Nelle sezioni più avanzate (es matrici):

testare sempre con gli assert (al momento non sono comodi da testare a mano, un giorno mi deciderò a scrivere una funzioncina che lanci automaticamente pytest)
evitare codice che richieda di stampare
Se è una funzione, specificare chiaramente se RITORNA un risultato o MODIFICA l'input. Evitare funzioni che facciano entrambe le cose. Evitare funzioni che stampano, a meno che non abbiano davvero senso (es: print log di simulazione)

Editing

Ci sono una serie di comandi per ricavare automaticamente il testo degli esercizi a partire dalle soluzioni, li trovate nella pagina Jupman: Usage

nota: per l'edizione italiana # write here diventa # scrivi qui e # SOLUTION diventa # SOLUZIONE
NOTA: i comandi purge rimuovono il testo sia dall'esercizio che dalla soluzione presenti negli zip, quindi i comandi li troverete solo nell'ipynb originale su Github

Quando si scrivono termini di Python o variabili, usare il backquote per evidenziarli, tipo True, anni
Nelle liste, iniziare le righe con carattere maiuscolo
Nelle print se possibile preferire la virgola es print("Hai fatto", salti, "salti") a formattazione / concatenazione.
per la formattazione delle stringhe, usare i % tipo "Hai fatto %s " % salti. Non usare f-string. Evitare concatenzioni tipo "fai " + str(n) + " salti"

Per i file creati: usare nomi di file in minuscolo, in inglese, sostituire spazi con trattini (-), non usare underscore _. I nomi dei dataset possono rimanere quelli originali.
evitare codice con input da utente: è difficile e noioso da testare, ma potrebbe andar bene per fare giochi
inclusività maschile/femminile: quando in dubbio, usare il criterio stocastico e tirare una moneta, croce usare maschile testa usare femminile, distribuendo equamente. Evitare forme intermedie tipo *, ə.

Usare frasi brevi: max 5 parole, eliminare articoli, congiunzioni
Separare frasi su più linee
Non mettere punteggiatura alla fine delle linee
Esercizi e testo devono stare nella stessa slide. Se proprio proprio non ci stanno, nella slide col codice riscrivere i vincoli (es 'NON usare .replace', etc)
Usare Markdown quando possibile