Alessio Treglia

Se avete seguito la prima parte del tutorial ora dovreste essere iscritti e pronti per partecipare alla stesura della documentazione. Da che parte si comincia? Ma ovviamente da una nuova guida che andrà inserita all’interno della propria pagina Prove, giusto per fare un po’ di pratica (beh, a dirla tutta, prima di scrivere anche solo una virgola, andrebbe letta a fondo GuidaWiki, ma passiamo oltre…).

Chi visita il wiki con frequenza giornaliera, avrà sicuramente fatto caso agli innumerevoli richiami alle linee guida inseriti da me nei commenti di modifica delle pagine. E qui si ritorna al motivo principale per il quale ho deciso di scrivere il presente tutorial: seguite le seguenti regole pressochè alla lettera e vi prometto di lasciarvi in pace!

Regole generali di buona scrittura

1. Non siate prolissi: una spiegazione sintetica dei comandi è necessaria, ma evitate di dilungarvi in spiegazioni teoriche, piuttosto sostituite tali divagazioni con link a fonti specifiche.
2. Fate buon uso della lingua italiana: scrivete in maniera corretta, utilizzate esclusivamente forme impersonali e prestate attenzione anche ai dettagli.
3. Declinate al singolare i termini stranieri plurali: file e non files, client e non clients, etc; quando possibile, sostituite i termini stranieri con le corrispondenti parole italiane.
4. La correttezza delle istruzioni e delle procedure contenute nella guida deve essere verificata: per porla sotto altri termini, non inserite comandi dei quali non si conoscono gli effetti.
5. Prendete come modello altre pagine già esistenti: ottimi esempi sono le Guide Consigliate come, ad esempio, BackupDelSistema/BackupConSbackup e UbuntuItaliano; altre ottime guide sono AmbienteGrafico/Gnome/Installazione e InternetRete/Condivisione/Autofs.

Regole stylistiche

1. Scelta del titolo: in formato NomeWiki e mai troppo lungo, deve essere adatto al contenuto della guida.
2. Suddivisione in paragrafi: utilizzare i titoli del primo livello
   

   = Titolo di primo livello =

   per i capitoli principali, gli altri livelli vanno usati solo all’interno dei paragrafi del livello immediatamente superiore, es:

    

   • = Installazione =
   • == Installazione da repository ==
   • === Abilitare il repository esterno ===
   • === Installazione del pacchetto ===
   • == Installazione da sorgenti ==
   • = Avvio del programma =

3. Uso delle maiuscolo: in generale la lettere maiuscola si utilizza solo dopo il punto, inoltre i nomi propri e gli acronimi inglesi vanno riportati con la sintassi originale: ad esempio GNOME è diverso da Gnome, checkinstall è diverso da Checkinstall, proprio come sudo e Sudo (la sintassi originale va rispettata anche dopo un ritorno a capo, in generale è vietato capitalizzare le iniziali secondo il gusto personale).
4. È obbligatorio utilizzare il ”’grassetto”’ per comandi, programmi, nomi delle finestre e combinazioni di tasti; si applica una piccola variante di tale regola ai pulsanti, alle schede e agli altri elementi dell’interfaccia grafica, i quali vanno grassettati e racchiusi da una coppia di apici basse, come nell’esempio:
   

   fare clic su «”’OK”’»

   Il grassetto va inoltre utilizzato nel testo degli avvertimenti (ma non nelle note).

5. Utilizzare il ”corsivo” per i nomi dei pacchetti; inoltre il corsivo è da preferire al grassetto per evidenziare piccoli gruppi di parole all’interno del testo;
6. Utilizzare il ””’grassetto corsivato””’ per i menu, separando le singole voci da frecce composte dai simboli - e > (es: ””’Applicazioni -> Accessori -> Editor di testo””’).
7. Racchiudere i nomi e le estensioni dei file fra due apici inversi (Alt+Gr+ì in Ubuntu, Alt+96 sotto Windows), come nell’esempio:
   

   `/etc/X11/xorg.conf`

8. Racchiudere i comandi del terminale in un blocco di codice. Ad esempio
   

   {{{
   sudo apt-get install banshee
   }}}

9. Le note, gli avvisi e i suggerimenti vanno inseriti con le relative tabelle presenti in StileDellePagine e seguendo le indicazioni di formattazione del testo (corsivo per quello delle note e grassetto per gli avvisi); piccola nota relativa agli avvertimenti: appesantiscono molto il testo, utilizzateli solo per mettere in risalto eventuali pericoli per l’integrità del sistema.
10. Utilizzare le immagini solo per semplificare le procedure attraverso l’uso di un esempio visivo.

Una volta memorizzate tali regole potrete considerarvi pronti per la terza e ultima parte del tutorial, che tratterà della vera e propria fase di creazione della vostra prima pagina!

Ciao!