Aiuto:Stile

Wiki> Linee guida sul contenuto
Le Linee guida sullo stile raccolgono gli elementi fondamentali da seguire per creare o modificare articoli, assicurando che mostrino ovunque un aspetto e un'impostazione tra loro consistenti. Queste guide di riferimento sono simili alle linee guida della Wikipedia. Le seguenti linee guida includono informazioni dettagliate sull'uso di stili e formattazione negli articoli di openSUSE wiki.

Usabilità generale

Stile neutrale

Lo stile di scrittura usto deve essere neutrale. Evitare l'utilizzo dei pronomi personali "io", "noi", e così via.

Scrivere breve e conciso

Mentre si scrive si dovrebbe valutare quanto prontamente si sarebbe disposti a continuare a leggere, oppure a smettere. Articoli mal scritti o eccessivamente prolissi molto probabilmente non verranno letti.

  • Si deve evitare di aggiungere contenuto irrilevante o ridondante. Le persone leggeranno gli articoli brevi e chiari, che forniscono le informazioni di cui hanno bisogno. Ma eviteranno quelli carichi di contenuti irrilevanti.
  • Utilizzare da cima a fondo una formattazione ordinata e consistente. Nessuno sarà disposto a leggere un articolo lungo che sia spezzato in sezioni usando disposizioni del testo (i cosiddetti layout) o colori male accostati. Questi, infatti, rendono soltanto la lettura più difficoltosa e servono solo ad allontanare il lettore.
  • Per rendere allora il tuo articolo utile e rinomato tra i lettori, mantienilo breve e conciso!

Vedere lo Sviluppo di un articolo su Wikipedia.

Struttura

Titolo

  • Il titolo dovrebbe essere chiaro e breve. Qui sono disponibili esempi di titoli mal scritti per alcuni articoli
  • Non utilizzare acronimi criptici, tranne il caso in cui si sia certi che sono ampiamente noti al pubblico cui è rivolto l'articolo.
  • Evitare di scrivere più parole (per esempio delle variabili) tutte attaccate, ciascuna con l'iniziale maiuscola (il cosiddetto CamelCase). Utilizzare invece gli spazi.
  • Utilizzare lo stesso stile di scrittura delle parole con iniziale maiuscola che è usato nella Wikipedia.
  • Evitare di usare i due punti come carattere di separazione nei titoli, poiché servono a denotare i namespace in MediaWiki.
  • L'uso dei caratteri speciali è da evitarsi. Utilizzare soltanto i caratteri [aA-zZ][0-9].

Titoli di sezione

  • Tutte le linee guida dei titoli suddette si applicano anche ai titoli di sezione.
  • Siccome i titoli di sezione vanno a formare l'indice dei contenuti, uno stile breve e telegrafico contribuisce a rendere la pagina leggibile e navigabile.
  • Evitare di ripetere il titolo dell'articolo nella prima sezione. La ridondanza non incoraggia a proseguire nella lettura.
  • Non utilizzare come nome della prima sezione le locuzioni A proposito di o Introduzione. La prima sezione di ciascun articolo è il paragrafo introduttore all'argomento, quindi ribadirlo esplicitamente non comunica nulla di nuovo al lettore.

Intestazioni

  • Utilizzare il marcatore (o carattere di markup) = per creare una intestazione. In questo modo verrà automaticamente creato l'indice dei contenuti a partire dalle intestazioni; ciò aiuta il lettore a spostarsi nella sezione a cui è interessato.
  • Iniziare con due segni di uguale ==, mai con uno solo =.
Icon-forbidden.pngVietato Un solo segno di uguale (=) fa sì che la dimensione del testo demarcato sia la stessa del titolo dell'articolo, cosa che non è usata in qualunque stile di scrittura usuale.
  • Non inserire collegamenti nelle intestazioni. Creare invece i collegamenti partendo dalla parola o dalla frase la prima volta che compare nella sezione.
  • Dividere le sezioni molto lunghe in qualche sottosezione, usando le intestazioni di livello inferiore (passando da un paragrafo a più sottopragrafi).
  • Utilizzare il marcatore ---- per creare una linea di separazione orizzontale prima di ciascuna intestazione di secondo livello (==), poiché questo aiuta a rendere più agevole la lettura dell'articolo
Esempio:
 ==Paragrafo 1==
 ===sottopragrafo 1.1===
 ===sottopragrafo 1.2===
 
 ----
 ==Paragrafo 2==
 ===sottopragrafo 2.2===
 ====sottopragrafo 2.2.1====
 =====sottopragrafo 2.2.1.1=====

 ----
 ==Paragrafo 3==

Contenuti

Corretta grafia di openSUSE

  • openSUSE è l'unico modo corretto di scrivere la parola openSUSE. "OpenSUSE", "openSuSE", OpenSuse" e altre variazioni sono tutte formattate in modo errato. Dal momento che il software MediaWiki non è in grado di gestire i titoli delle pagine wiki scritti tutto in minuscolo, utilizzare Template:Lowercase_title quando si sta scrivendo una pagina wiki il cui titolo inizia con "openSUSE".
  • Non utilizzare i caratteri di marchio registrato (come ad esempio © o ®) poiché sono di ostacolo alla lettura della pagina.
  • Si noti che la grafia "SuSE Linux" e "SUSE Linux" sono deprecate. Ad eccezione di quando si fa esplicitamente riferimento ad un rilascio che è più vecchio di openSUSE (cioè 10.1 e rilasci precedenti) per finalità storiche, oppure a SUSE Linux Enterprise Server (SLES) o SUSE Linux Enterprise Desktop (SLED), usare "openSUSE".

Duplicazione

Evitare di duplicate gli sforzi.

  • Controllare prima l'elenco di HOWTO per openSUSE (e la pagina in inglese corrispondente, ivi linkata). Lì è già presente una vasta raccolta di articoli. Se ne esiste uno che copre l'argomento su cui si vuole scrivere allora è meglio dedicare un po' di tempo a leggere quell'articolo e vedere se può essere migliorato o espanso.
  • Il forum di openSUSE possiede una raccolta di HOWTO, precisamente nel forum Advanced How To/FAQ (in inglese).
  • Una grossa collezione di HOWTO è disponibile, in inglese, sul sito di The Linux Documentation Project (lì è disponibile anche il collegamento alla versione italiana, se raggiungibile. Si può anche cercare di accedere all'Italian Linux Documentation Project).

Acronimi e abbreviazioni

  • Quando si inserisce un nuovo acronimo in un articolo, utilizzare alla sua prima occorrenza il nome per esteso seguito dalla sua forma abbreviata posta tra parentesi tonde. Per esempio: Section titles automatically form the table of contents (TOC).
  • Evitare abbreviazioni complesse poiché rendono gli articoli più difficoltosi da leggere.
  • Utilizzare sempre abbreviazioni standard e largamente comprensibili dato che i cambiamenti legati all'innovazione possono portare ad interpretazioni errate.

Variabili

Capita a volte che un comando inserito sia specifico dell'utente o del sistema che sta usando, come i dispositivi di sistema o il nome utente. Si dovranno allora seguire le seguenti convenzioni:

  • <nomeutente>, per esempio se in un comando è presente il percorso /home/<nomeutente>
  • sdX per i dispositivi associati alle unità di archiviazione; è fondamentale che la lettera X sia scritta in maiuscolo cosicché un copia e incolla del comando provocherà un errore di esecuzione, invece che causare danni
  • Sarà necessario spiegare al lettore con che cosa deve sostituire <nomeutente> o sdX, non tutti infatti sono pratici delle convenzioni di scrittura a cui si è accennato qui.

Sicurezza per gli utenti inesperti

Attenzione: Prestare particolare attenzione quando si forniscono istruzioni che devono essere eseguite con privilegi di super-utente (ossia dell'utente root). I comandi come dd, rm, fdisk, possono causare molti danni se usati senza sapere ciò che si sta facendo. Spesso i nuovi utenti non sono in grado di capire il comando, per cui ne faranno semplicemente il copia e incolla:

  • Utilizzare il codice di esempio che, se copiato e incollato direttamente in una riga di comando, darà come risultato un errore di esecuzione e non una catastrofe.
Errato: 
# dd if=openSUSE-11.2-KDE4-LiveCD-i686.iso of=/dev/sda
 /dev/sda è il primo disco rigido ed è presente in ogni computer.
Corretto: 
# dd if=openSUSE-11.2-KDE4-LiveCD-i686.iso of=/dev/sdX
/dev/sdX non esiste normalmente nelle installazioni, e dd restituirà un errore riguardo al dispositivo /dev/sdX non esistente.

Immagini

Posizionare le immagini

Si veda l'articolo Wikipedia (in inglese) Image markup per avere consigli sul miglior marcatore (o markup) da usare. Per idee ed esempi su come posizionare le immagini rispetto al testo vedere la pagina Wikipedia in inglese Picture tutorial. Può anche essere utile questa pagina di aiuto della Wikipedia in lingua italiana sul Markup Immagine.

Formati

  • I file di disegni, icone e altre immagini del genere (sostanzialmente quelle contenenti ampi e semplici blocchi di uno stesso colore) dovrebbe essere in formato PNG.
  • Le foto dovrebbero essere in formato JPEG.
  • Le animazioni dovrebbero essere in formato GIF animato.
Si noti che le vecchie versioni degli articoli non mostrano le corrispondenti versioni vecchie delle immagini, bensì le ultime, a meno che sia stato cambiato o modificato il nome ai file delle immagini.

Colori

Se si decide di assegnare un certo colore ad alcuni elementi della pagina, vedere alla pagina en:Help:Colors le tabelle dei colori con i colori standard per la distribuzione e il sito web di openSUSE.

Commenti

  • Non disseminare il testo dell'articolo di commenti o domande riguardanti la stesura dell'articolo (sia riguardanti forma che contenuto). Utilizzare invece la pagina di discussione per l'articolo.
  • Se si vogliono lasciare delle informazioni per gli altri editori, inserire dei commenti invisibili al lettore ordinario dell'articolo utilizzando i tag che indicano un commento.
 <!-- Questo è un commento invisibile.  -->

Pagine più richieste

Per far sapere che esiste una richiesta per qualche articolo che ancora non esiste, creare un collegamento all'articolo richiesto nel testo di un articolo esistente. Se ci sono almeno due collegamenti allo stesso articolo non esistente, quest'ultimo comparirà nell'elenco delle Pagine più richieste, che è una fonte di ispirazione per tanti nuovi autori di wiki. Benché non tutto ciò che si trova in quella pagina sia davvero necessario, il buon senso e l'esperienza dell'editore gli suggeriranno quale articolo scegliere dall'elenco.

Elementi

Quando si scrive è necessario assicurarsi di seguire le seguenti convenzioni.

Marcatori Wiki

Benché sia possibile usare i tag HTML per formattare una pagina, utilizzando i marcatori di MediaWiki (anche noti come markup) il testo sorgente risulterà più facile da leggere e modificare. Può inoltre essere utile visionare la Scheda di riferimento per Wiki e il codice sorgente di alcuni articoli.

Scorciatoie e comandi della tastiera

F5 e Tab

  • Codice: <code>Tasto da premere</code>
  • Descrizione: Pulsante della tastiera da premere.
  • Dove: Ovunque

Percorso a file o directory

/usr/src/linux e /etc/SuSE-release

  • Codice: <tt>/percorso/versp/directory/oppure/file</tt>
  • Descrizione: Illustra il percorso verso directory o file.
  • Dove: Ovunque

Input del comando

$ comando da utente
# comando da root
  • Codice: {{Shell|$ comando da utente}}, {{Shell|# comando da root}} oppure <div class="shell">$ utente/# comando da root</div>
  • Descrizione: Comando da inserire.
  • Dove: Ovunque

Output del comando

test restituito nell'output del comando
  • Codicee: (spazio vuoto)breve testo di output oppure <pre>lungo testo di output</pre>
  • Descrizione: Illustra il risultato di un comando inserito.
  • Dove: Ovunque

Trascrizioni di incontri

... Contenuti ...
  • Codice: <div class="minutes"> ... Contenuti ... </div>
  • Descrizione: Visualizza trascrizioni di incontri.
  • Dove: Ovunque

Tabelle

Intestazione 1 Intestazione 2 Intestazione 3 Intestazione 4 Intestazione 5 Intestazione 6
Testo evidenziato Testo evidenziato Testo evidenziato Testo Testo Testo evidenziato
Testo Testo Testo Testo Testo Testo evidenziato
Testo Testo Testo Testo Testo Testo evidenziato
  • Codice: Vedi pagina sorgente.
  • Descrizione: Visualizza una tabella con testo, facoltativamente evidenziato.
  • Dove: Ovunque

Modelli

Vedere le Linee guida per i Modelli.

Vedi anche

Collegamenti esterni

Estratto da "https://it.opensuse.org/index.php?title=Aiuto:Stile&oldid=10883"