BR

Guida di stile per la documentazione

Lo scopo di questa guida è quello di essere un punto di riferimento per tutti i collaboratori di Ubuntu-it nello scrivere documentazione per il wiki di Ubuntu-it, ma non solo. La guide create seguendo queste regole risulteranno quindi consistenti per rendere la lettura da parte degli utenti più facile.

Questa guida non spiega come usare lo strumento del wiki né come fare per ottenere delle determinate formattazioni del testo (grassetto, corsivo, ecc...).

Regole generali

Per scrivere una buona guida, o della buona documentazione, è utile tenere a mente questi semplici concetti.

Una buona guida deve essere:

• Chiara BR Esprimere in modo semplice e non troppo prolisso i concetti.

• Consistente BR Usare una terminologia approvata e standardizzata all'interno di tutte le guide, facendo uso dei glossari approvati.

• Concisa BR Deve essere focalizzata per l'uso immediato, non deve essere un'enciclopedia.

• Completa BR Quanto più possibile. Deve descrivere, se non tutti, gli aspetti più importanti di un programma o prendere in esame le parti più salienti di ciò che si vuole descrivere.

Delle buone regole

Delle semplici regole per scrivere una buona guida professionale:

• Scrivere in modo impersonale, non rivolgendosi mai all'utente finale, restando sempre neutrali.
• Cercare di non essere troppo prolissi: un utente si può stufare a leggere molto e per chi cerca delle informazioni precise il compito può essere difficoltoso.
• Evitare commenti riguardo il programma e il suo futuro sviluppo, è necessario scrivere riguardo a ciò che si ha davanti agli occhi.
• Scrivere in modo neutrale: non aggiungere commenti personali, umoristici o sarcastici, possono distrarre l'utente.
• Quanto più è possibile, usare degli esempi espliciti piuttosto che descrivere dettagliatamente una procedura.

A chi scrivere

È importate, quando si scrive una guida, pensare a chi è rivolta, quali informazioni possono essere necessarie e anche come queste informazioni devono essere rappresentate.

Gli utenti solitamente usano le documentazione per avere una risposta a una specifica domanda, non leggono la documentazione per divertimento, è quindi necessario cercare di dare delle risposte chiare e precise a queste domande.

Nuovi utenti

I nuovi utenti solitamente fanno riferimento alla documentazione o ai manuali per cercare delle risposte precise, per risolvere dei problemi che possono affliggerli o per capire come installare o lavorare con le nuove applicazioni. In questo caso è utile rappresentare le informazioni in base all'attività da svolgere, con degli elenchi numerati descrivendo un'azione alla volta.

Utenti esperti

Gli utenti esperti solitamente utilizzano le guide o la documentazione come riferimento, è quindi utile che la guida sia abbastanza completa e ben organizzata nelle sue sezioni.

Anchor(modelli)

Struttura

Per rendere le guide il più omogenee possibile, all'interno del wiki sono presenti dei modelli prestabiliti da applicare alla particolare guida. Sono identificate tre categorie di documentazione:

• documentazione generale, fa uso del modello [:DocumentazioneModello]

• documentazione per computer portatili, fa uso del modello [:NotebookModello]

• documentazione per i giochi, fa uso del modello [:GiochiModello]

È necessario attenersi strettamente a questi modelli nel creare una nuova guida.

Struttura del documento

Nella presentazione delle informazioni, è buona norma numerare i passi descritti utilizzando degli elenchi numerati. In questo modo è possibile riferirsi a un determinato passo di una procedura e le informazioni risultano più organizzate e di più facile consultazione.

Indice

Inserire in ogni documento un indice contenente i titoli delle sezioni. Nei modelli prestabiliti delle pagine tale indice è già inserito e il suo codice è questo:

[[BR]]
||<tablestyle="float:right; font-size: 0.9em; width:35%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;">'''Indice'''[[BR]] [[TableOfContents]]||

Sezioni

Suddividere il documento in sezioni in base agli argomenti trattati:

• usare il livello uno per le sezioni principali;
• usare il livello due per le sottosezioni usando dei titoli specifici per ogni sottosezione;
• non scendere mai al di sotto del livello tre.

All'interno delle sezioni, cercare, quando possibile, di numerare i passi da eseguire.

Per informazioni su come scrivere i titoli delle sezioni, consultare la sezione [#titoli Titoli delle sezioni].

Traduzione di documenti

Se il documento creato è la traduzione di una guida presente nel wiki internazionale di Ubuntu o di un'altra guida, è necessario inserire nella sezione Ulteriori risorse del modello della pagina il collegamento alla guida originale.

Tale collegamento, se preso dal wiki di Ubuntu, deve essere reso in questo modo:

 * [wiki:Ubuntu/NomeDocumento Documento originale]

Altrimenti in questo modo:

 * [http://collegamento Documento originale]

Anchor(altridoc)

Riferimenti ad altri documenti

All'interno di una guida è possibile e raccomandato fare riferimento alle altre guide presenti nel wiki per semplificare il lavoro di scrittura.

Per esempio, se si sta scrivendo una guida e bisogna indicare di installare un pacchetto, non serve scrivere ogni volta la procedura dettagliata per l'installazione, basta fare riferimento alla guida dedicata all'argomento in questione indicando semplicemente i pacchetti da installare.

Altro esempio sono le guide in cui è indicato di modificare dei file con un editor di testo. Per rendere la guida il più generale possibile, e per non vincolare un utente all'utilizzo di un determinato editor di testo, basta indicare la pagina all'interno del wiki che descrive gli editor di testo più comuni per le versioni di Ubuntu.

Anche nel portale giochi, in cui la procedura di installazione dei giochi tramite Wine è sempre la stessa, basta indicare l'apposita guida.

Un breve elenco delle guide a cui si può fare riferimento:

• [:EditorDiTesto:Editori di testo]

• [:Emulatori/Wine:Wine]

• [:AmministrazioneSistema/InstallareProgrammi:Installare i programmi]

Come scrivere

Lingua

La lingua utilizzata per scrivere la documentazione è l'italiano. Per una traduzione dei termini stranieri o per i termini più comuni, fare riferimento al [:GruppoTraduzione/Glossario:glossario del Gruppo traduzione].

• Evitare l'uso di inglesismi: parole come "settare", "loggare", ecc...
• Evitare l'uso dei plurali inglesi: "files", "directories", "repositories", ecc..., in italiano assumono sempre la forma singolare.

• Evitare l'uso di emoticon o faccine.

Anchor(titoli)

Titoli delle sezioni

Per scrivere i titoli delle sezioni, seguire queste regole:

• non scrivere mai le parole dei titoli con tutte le iniziali maiuscole, non è forma italiana corretta;
• mantenere i titoli delle sezioni corti;

È buona norma utilizzare il tempo infinito nello scrivere un titolo di una sezione.

Anchor(maiuscole)

Maiuscole e minuscole

Come spesso si vede nei documenti inglesi, i titoli dei documenti o delle sezioni di un documento, presentano le parole tutte con l'iniziale maiuscola. Questa pratica è assolutamente da evitare in italiano. Non è un buon esempio di scrittura.

Alcune parole, invece, vanno riportate con le maiuscole o minuscole corrispondenti. Alcuni esempi possono essere:

• Ubuntu, va sempre riportato con l'iniziale maiuscola quando ci si riferisce al progetto o al sistema operativo, se presente all'interno del nome di un pacchetto va riportato come l'originale;
• riferimenti a documenti in inglese, in questo caso è giusto rispecchiare l'originale;

• i nomi propri o i nomi tipo GNOME, KDE, GNU, che devono essere riportati in maiuscolo;

• gli acronimi inglesi, i quali vanno riportati come l'originale (generalmente tutte lettere maiuscole) se compaiono all'interno del testo, con solo l'iniziale capitalizzata nel caso compaiano nel titolo.

Anchor(impersonale)

Impersonale

Nello scrivere una guida va utilizzata una forma il più impersonale possibile, non rivolgendosi mai all'utente, ma mantenendo un tono neutro. È anche necessario non personificare l'hardware o il software, evitando di "far parlare" o agire il programma in prima persona.

Tempi verbali

È preferibile utilizzare il tempo indicativo presente nello scrivere i documenti.

Questo non è obbligatorio, dato che in alcune circostanze non è di facile realizzazione. Resta comunque cura dell'autore del documento assicurarsi che i tempi verbali siano corretti e consistenti all'interno di tutto il documento.

Uso della "d" eufonica

Le forme eufoniche vanno usate solamente quando la vocale della parola che segue è la stessa (es: "Alessandro e Alberto").

L'unica eccezione a questa regola è data dall'espressione "ad esempio", anche se è preferibile usare l'espressione "per esempio".

Congiunzione e

La virgola prima della congiunzione "e" non va mai messa a meno che la frase non sia un inciso.

Alcune forme canoniche

Quando all'interno della guida si vuole indicare un riferimento a un'altra guida come consultazione, impostare la frase nei seguenti modi:

• Per maggiori informazioni, consultare XYZ.
• Per maggiori informazioni, consultare la guida XYZ.
• Per maggiori informazioni riguardo ABC, consultare XYZ.

Nel caso in cui si voglia descrivere una procedura per svolgere un'azione, elencandone i passi necessari, usare una forma simile alla seguente:

• Per [avviare XYZJ], procedere come segue:

Formattazione del testo

Per rendere più omogenee le guide, vengono adottate all'interno del wiki queste regole per la formattazione del testo in particolari casi.

Anchor(nomifile)

Nomi dei file

All'interno di un documento i nomi dei file devono essere formattati attraverso l'uso di un apice inverso (AltGr+ì) «`nome file`». Esempio:

Modificare il file `/etc/X11/xorg.conf`

È possibile ottenere lo stesso effetto anche attraverso l'uso di tre parentesi graffe «{{{nome file}}}» in una riga. Esempio:

Modificare il file {{{/etc/X11/xorg.conf

}}}

Riferimenti all'interno di file

Se ci si riferisce a delle voci, parole o sezioni all'interno di un file, queste devono essere formattate attraverso l'uso di un "blocco di codice":

All'interno del file `/etc/X11/xorg.conf` modificare la riga: {{{
Section "ServerLayout"
} }} # lo spazio nel documento non deve essere presente!

che viene reso come:

All'interno del file /etc/X11/xorg.conf modificare la riga:

Section "ServerLayout"

Formato dei file (estensioni)

Se all'interno di un documento ci si riferisce al formato di un file (estensione), questo deve essere formattato tramite l'uso degli apici inversi «`formato file`». Esempio:

Convertire i pacchetti `.rpm` in formato `deb`

Nomi dei pacchetti di installazione

Se all'interno di un documento ci si riferisce al nome di un pacchetto installato, questo deve essere formattato tramite l'uso del corsivo con due apici «''nome pacchetto''». Esempio:

È necessario eliminare il pacchetto ''ubuntu-sounds'' ...

Nomi dei programmi

I nomi dei programmi come Totem, Synaptic, Firefox o altri, devono essere formattati attraverso l'uso del grassetto con tre apici:

Il programma '''Firefox''' ...

Anchor(menu)

Navigazione dei menù

Quando in un documento è necessario indicare i menù da seguire per eseguire un determinato compito, la navigazione dei menù dovrebbe essere resa attraverso l'uso di cinque apici «'''''navigazione dei menu'''''».

La separazione tra un menù e l'altro è resa attraverso il simbolo «->», un trattino orizzontale e il simbolo di maggiore:

Avviare '''gedit''' da '''''Applicazioni -> Accessori -> Editor di testo'''''

Anchor(gui)

Voci di menù e altri elementi dell'interfaccia grafica

Quando ci si riferisce a delle voci di un menù, come nel caso del menù File della barra dei menù o a un'opzione presente in una finestra o un dialogo, questi vanno formattati attraverso l'uso del grassetto con tre apici.

Altri elementi dell'interfaccia da rendere attraverso l'uso del grassetto:

• titoli di finestre e dialoghi;
• opzioni;
• caselle di selezione, pulsanti radio;
• pulsanti;
• caselle di testo;
• nomi delle schede;
• etichette.

Nel in cui caso si voglia differenziare meglio l'opzione o l'elemento indicato dal resto del testo, racchiuderlo tra due apici bassi, «».

Navigazione all'interno di un documento

Quando in un documento ci si deve riferire a una sezione interna dello stesso documento è buona norma inserire un collegamento diretto a quella sezione del documento. Questo è possibile attraverso l'uso della macro [[Anchor(nome anchor)]] da inserire vicino la sezione interessata. Il collegamento viene gestito normalmente attraverso l'uso delle parentesi quadre, «[]»:

la macro in questo documento è stata inserita vicino la sezione «Nomi dei file»: [[Anchor(nomifile)]]

ora inseriamo il collegamento a quella sezione:

[#nomifile Nomi dei file]

che viene reso come: [#nomifile Nomi dei file].

Quando ci si riferisce a una sezione interna di un documento, sia dello stesso documento che di un altro documento, riportare sempre per intero il nome della sezione a cui ci si riferisce.

Comandi dal terminale

Quando all'interno di un documento si deve inserire un comando da eseguire in un terminale, questo deve essere rappresentato con un "blocco di codice":

In un terminale digitare
{{{
sudo apt-get install ...
} }} # lo spazio nel documento non deve essere presente!

che viene reso come:

In un terminale digitare:

sudo apt-get install ...

Combinazioni di tasti

Se all'interno di un documento è necessario inserire delle combinazioni di tasti da premere, queste devono essere formattate attraverso l'uso del grassetto con tre apici:

Premere i tasti '''Ctrl+Alt+z''' ...

Indirizzi internet

Benché gli indirizzi web con protocollo http:// vengano identificati automaticamente dal wiki, è buona norma racchiudere questi tra due parentesi quadre.

Nel caso in cui si faccia riferimento a un indirizzo non riconosciuto dal wiki, come i nomi dei server IRC o indirizzi numeri, devono essere identificati attraverso l'uso di due apici inversi, `indirizzo.non.riconosciuto`. Esempio:

`192.168.1.2`
`irc.freenode.net`

È possibile ottenere lo stesso effetto anche attraverso l'uso di tre parentesi graffe «{{{indirizzo.non.riconosciuto}}}» in una riga. Esempio:

{{{192.168.1.2

}}}

È consigliato identificare i canali IRC attraverso l'uso del grassetto. Esempio:

... entrare nel canale '''#ubuntu-it''' nel server `irc.freenode.net`...

Anchor(noteavvisi)

Note, avvisi e suggerimenti

Per segnalare al lettore alcune particolarità che possono essere escluse dal testo principale della guida o per porre l'attenzione su un particolare, è possibile utilizzare rispettivamente una nota, un avviso/avvertimento o un suggerimento.

• Nel riportare una nota, un avviso/avvertimento o un suggerimento, il testo non deve iniziare con le parole «Nota:», «Avviso:», «Avvertimento:» o «Suggerimento:». L'uso delle icone serve per indicare la tipologia del testo a seguire.

• All'interno di una nota, di un avviso o un suggerimento non vanno inseriti blocchi di codice, comandi per il terminale o quanto altro debba essere formattato con l'utilizzo delle parentesi graffe su più righe. Nel caso in cui questo fosse necessario, è preferibile non utilizzare una nota o un avviso, ma includere la nota o l'avviso stessi nel documento.

• Nel caso in cui il testo all'interno della tabella superi la dimensione dell'icona, è possibile allineare quest'ultima in alto nella tabella inserendo il simbolo «^» come:

  ||<tablestyle="text-align: justify; width:100%; " style="border:none;" 5% ^>[[Immagine(Icone/Piccole/note.png,,center)]] ||<style="padding:0.5em; border:none;">Testo in tabella.||

Note

La nota va riportata utilizzando il corsivo per il testo della nota. Da questa formattazione vengono esclusi i nomi dei programmi o altre istruzioni che presentano una loro particolare formattazione.

È necessario quindi prestare attenzione all'uso corretto degli apici.

Per inserire una nota, utilizzare il seguente codice:

||<tablestyle="text-align: justify; width:100%; " style="border:none;" 5%>[[Immagine(Icone/Piccole/note.png,,center)]] ||<style="padding:0.5em; border:none;">''Testo della nota in cui vengono esclusi i nomi dei'' '''programmi'''. ||

Avvisi e avvertimenti

Nel caso di un avviso/avvertimento, il testo va riportato utilizzando il grassetto.

Per inserire un avviso, utilizzare il seguente codice:

||<tablestyle="text-align: justify; width:100%; " style="border:none;" 5%>[[Immagine(Icone/Piccole/warning.png,,center)]] ||<style="padding:0.5em; border:none;">'''Testo dell'avviso/avvertimento.''' ||

Suggerimenti

In aggiunta alle note e agli avvertimenti, è possibile far uso di suggerimenti riportando il testo con carattere ordinario.

Per inserire un suggerimento, utilizzare il seguente codice:

||<tablestyle="text-align: justify; width:100%; " style="border:none;" 5%>[[Immagine(Icone/Grandi/info.png,,center)]] ||<style="padding:0.5em; border:none;">Testo del suggerimento. ||

Anchor(immagini)

Immagini

All'interno delle guide è possibile caricare delle immagini, screenshot, delle applicazioni o riguardo l'argomento trattato, solo se queste sono necessarie alla semplificazione della guida attraverso l'uso di un esempio visivo.

Le immagini non vanno usate per abbellimento visivo o per riempire una pagina.

Tenere a mente queste regole:

• non usare le immagini, screenshot, indiscriminatamente;

• assicurarsi che ogni nuova immagine sia veramente necessaria, è bene ricordarsi che l'utente solitamente ha l'applicazione sotto gli occhi;
• gli utenti devono scorrere la pagina per passare al successivo blocco di informazioni, le immagini possono rallentare la lettura;
• le immagini vanno mantenute aggiornate con i nuovi rilasci dell'applicazione;
• usare il tema predefinito di Ubuntu e catturare solo la finestra dell'applicazione;
• se deve essere incluso anche lo sfondo della scrivania, usare quello predefinito di Ubuntu;

• usare un nome utente fittizio, soprattutto se vengono catturate immagini del terminale. Usare come none utente mario e per il computer mario-desktop;

• nel portale giochi è consentito utilizzare una sola immagine;

• per le immagini usare il formato PNG, nel portale giochi è possibile usare anche immagini JPEG.

Nel caso si vogliano inserire delle immagini e corredarle con delle descrizioni posizionate a lato, è bene allineare l'immagine a destra e mettere la didascalia o la descrizione a sinistra. Nel caso di schermi di dimensioni ridotte, solo l'immagine risulterebbe nascosta, la descrizione sarebbe ancora visibile.

CategoryComunita