Guida di stile per la documentazione

Questa guida si pone come punto di riferimento per tutti i collaboratori di Ubuntu-it per la redazione di documentazione per il wiki di Ubuntu-it. La guide create seguendo le regole qui stabilite risulteranno coerenti tra loro per forma e struttura: ciò renderà più facile la lettura da parte degli utenti.

Questa guida non spiega come usare lo strumento del wiki né come fare per ottenere determinate formattazioni del testo (grassetto, corsivo, ecc...). Per ottenere tali informazioni, consultare l'indice delle pagine di aiuto.

Regole generali

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

Una buona guida deve essere:

• Chiara
  Esprimere i concetti in modo semplice.

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

• Concisa
  Deve essere orientata all'uso immediato: il wiki non è un'enciclopedia.

• Completa
  Quanto più possibile. Deve descrivere, se non tutti, almeno 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 rivolgersi mai direttamente al lettore, restando sempre neutrali. La prosa dovrà assomigliare quanto più possibile a quella tipicamente descrittiva dei manuali tecnici, piuttosto che a quella narrativa dei racconti/romanzi.
• Preferire un'esposizione sintetica: la prolissità mette a dura prova l'attenzione del lettore e può pregiudicare la comprensione dei concetti. Chi consulta il wiki in genere cerca informazioni o soluzioni precise a un proprio dubbio o problema.
• 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 che possono distrarre l'utente.
• Quanto più è possibile, usare degli esempi espliciti piuttosto che descrivere estensivamente una procedura.

A chi scrivere

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

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 presentare le informazioni in base all'attività da svolgere, utilizzando gli elenchi numerati per descrivere 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 nei suoi paragrafi.

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 lo strumento dell'elenco numerato. 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 dei paragrafi. Nei modelli prestabiliti delle pagine tale indice è già inserito e il suo codice è questo:

<<BR>>
<<Indice()>>

Come argomento, la macro riceve il livello dei titoli da far apparire nell'indice e la posizione dell'indice, per esempio:

<<Indice(depth=2 align=left)>>

farà apparire i titoli fino al livello due creando un indice sulla sinistra della pagina.

Il valore predefinito per la posizione è "right". Le possibili combinazioni per la macro sono:

<<Indice()>>
<<Indice(depth=INTERO)>>
<<Indice(depth=INTERO align=left|right)>>
<<Indice(align=left|right depth=INTERO)>>

Paragrafi

Suddividere il documento in paragrafi in base agli argomenti trattati:

• usare il livello uno per i paragrafi principali;
• usare il livello due per i sotto-paragrafi usando dei titoli specifici per ogni sotto-paragrafo;
• non scendere mai al di sotto del livello tre.

All'interno dei paragrafi, cercare, quando possibile, di numerare i passi da eseguire.

Per informazioni su come scrivere i titoli dei paragrafi, consultare il paragrafo Titoli dei paragrafi.

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 nel paragrafo 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:

 * [[WikiUbuntu/NomeDocumento | Documento originale]]

Altrimenti in questo modo:

 * [[http://collegamento | Documento originale]]

Riferimenti ad altri documenti

Per semplificare il lavoro di scrittura, all'interno di una guida è possibile (e raccomandato) fare riferimento alle altre guide presenti nel wiki.

Per esempio, quando nel corso della scrittura si indica l'installazione di un pacchetto, evitare la descrizione delle varie modalità possibili: basta infatti rimandare alla guida dedicata, indicando semplicemente i pacchetti da installare.

Quando si presenti la necessità di modificare un file di configurazione, non è consigliabile indicare il proprio editor preferito o quello presente in maniera predefinita nella propria versione di Ubuntu. 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:

• Editori di testo

• Wine

• 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 glossario del Gruppo traduzione.

• Evitare l'uso di inglesismi: ad esempio parole come «settare», «loggare», ecc.
• Evitare l'uso dei plurali inglesi: ad esempio «files», «directories», «repositories», ecc., che in italiano assumono sempre la forma singolare.
• Evitare l'uso di termini dialettali, gergali o locali.
• Evitare l'uso di forme lessicali arcaiche, auliche o desuete.

• Evitare l'uso di emoticon ed emoji.

Titoli dei paragrafi

Per scrivere i titoli dei paragrafi, seguire queste regole:

• non scrivere mai le parole dei titoli con tutte le iniziali maiuscole: non è forma italiana corretta;
• i titoli devono essere sintetici: meglio utilizzare poche parole chiave piuttosto che frasi complete.

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

Maiuscole e minuscole

Come spesso si vede nei documenti inglesi, i titoli dei documenti o dei paragrafi 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;
• i nomi propri;

• i nomi di software o di specifici progetti vanno riportati come l'originale, rispettando la corrispondenza maiuscole/minuscole assegnata dagli autori. Alcuni esempi: «GNU/Linux» e non «Gnu/Linux»; «Ubuntu MATE» e non «Ubuntu Mate»; «GNOME» e non «Gnome»; «KDE» e non «Kde»; «Xfce» e non «XFCE»; «LXQt» e non «LXQT»; «LibreOffice» e non «Libreoffice»;

• gli acronimi inglesi, i quali vanno riportati come l'originale (generalmente tutte lettere maiuscole) se compaiono all'interno del testo, con solo l'iniziale maiuscola nel caso compaiano nel titolo;
• riferimenti a documenti in inglese, in questo caso è giusto rispecchiare l'originale.

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 "ad", "ed" e "od" vanno usate solamente quando la vocale della parola che segue è la stessa delle congiunzioni "e"/"o" oppure della preposizione "a".
Va quindi usata in espressioni come «Firenze ed Empoli» oppure «ad Alessandro». Al contrario, la "d" eufonica non va usata in espressioni quali «a Empoli» oppure «Alessandro e Alberto».

Fanno eccezione pochissime espressioni, fra cui «ad esempio» (in molti casi è preferibile usare l'espressione «per esempio»).

Apostrofi e elisioni

Quando non strettamente necessario, è bene limitare l'uso delle elisioni. Ciò sia per migliorare la leggibilità del testo (l'occhio umano tende a distinguere più facilmente due parole se scritte separate), sia per limitare l'uso degli apostrofi (che in alcuni casi potrebbero influire sul funzionamento dell'editor del wiki).
Ad esempio preferire forme quali «tempi di avvio» a «tempi d'avvio», «si usa» a «s'usa», «gli italiani» a «gl'italiani» ecc.

Congiunzione e

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

Nomi e simboli delle unità di misura

Nello scrivere i nomi e i simboli delle unità di misura si tengano presenti le seguenti linee generali:

• I nomi delle unità di misura si scrivono sempre minuscoli.
• I simboli delle unità di misura si scrivono con la prima lettera maiuscola solo se derivati da nomi propri di persona.
• I prefissi si scrivono in maiuscolo solo a partire da mega «M».

• In informatica vengono spesso usati i prefissi binari.

Per approfondimenti si legga la pagina di Wikipedia sul sistema internazionale di unità di misura.

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.

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`

Riferimenti all'interno di file

Se ci si riferisce a delle voci, parole o paragrafi 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`

che viene reso come: Convertire i pacchetti .rpm in formato deb

Testo inciso

Se l'esecuzione di una procedura o singolo passaggio è particolarmente critico, lo si può evidenziare tramite l'uso della sottolineatura « __testo inciso__ ». Esempio:

__È fortemente raccomandato__ consultare la pagina manuale. 

che viene reso come: È fortemente raccomandato consultare la pagina manuale.

Nomi dei pacchetti di installazione

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

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

In alternativa e nel caso in cui il pacchetto debba essere installato, è possibile far uso del protocollo apt-url, la dicitura corretta è:

È necessario installare i pacchetti [[apt://ubuntu-sounds,gnome-games | ubuntu-sounds, gnome-games]] ...

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''' ...

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 «→» realizzabile con la combinazione di tasti AltGr+i):

Avviare '''gedit''' da '''''Applicazioni → Accessori → Editor di testo'''''

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 caso in cui 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 un paragrafo interno allo stesso documento è buona norma inserire un collegamento diretto a quel paragrafo del documento. Questo è possibile attraverso l'uso della macro <<Anchor(nome anchor)>> da inserire vicino al paragrafo interessato. Il collegamento viene gestito normalmente attraverso l'uso delle parentesi quadre, «[ ]»:

la macro in questo documento è stata inserita vicino al paragrafo «Nomi dei file»: <<Anchor(nomifile)>>

ora inseriamo il collegamento a quel paragrafo:

[[#nomifile|Nomi dei file]]

che viene reso come: Nomi dei file.

Quando ci si riferisce a un paragrafo interno di un documento, sia dello stesso documento che di un altro documento, riportare sempre per intero il nome del paragrafo 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 ...

Intestazione script

Per riportare il testo degli script si utilizzano blocchi di codice come per i comandi da terminale. Occorre però notare che comunemente gli script riportano nella prima riga stringhe del tipo:

#!/bin/bash

#!/usr/bin/env python

Il simbolo # a inizio riga nasconderebbe la stringa commentandola. Per ovviare al problema basta far precedere il testo da una nuova riga con i simboli #! come riportato in questo esempio:

{{{ 
#!
#!/bin/bash
touch ciao_mondo.txt
echo "Ciao mondo!" > ciao_mondo.txt
} }} # lo spazio nel documento non deve essere presente!

che viene reso come:

#!/bin/bash
touch ciao_mondo.txt
echo "Ciao mondo!" > ciao_mondo.txt

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''' ...

Se l'ultimo tasto della combinazione è una lettera, va riportata al maiuscolo.

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`

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

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

Bug su Launchpad

Se all'interno di un documento è necessario inserire un collegamento ad un bug segnalato su Launchpad, utilizzare la macro:

<<Bug(ubuntu NUMERO_BUG)>>

sostituendo alla voce NUMERO_BUG il corrispondente numero di segnalazione. Il risultato sarà simile al seguente:

#1234567

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 aspetto, è possibile utilizzare rispettivamente una nota, un avviso/avvertimento o un suggerimento.

• {{{#!wiki note
  Questa è una nota.
  }}}

• {{{#!wiki important
  Questo è un  avviso/avvertimento.
  }}}

• {{{#!wiki tip
  Questo è un suggerimento.
  }}}

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 nome 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.

CategoryComunitaDocumentazione