|
⇤ ← Versione 1 del 28/11/2007 23.17.50
Dimensione: 64
Commento: bloccata
|
Dimensione: 11573
Commento: importato il documento, dopo aggiorno con la vecchia StileDellePagine
|
| Le cancellazioni sono segnalate in questo modo. | Le aggiunte sono segnalate in questo modo. |
| Linea 1: | Linea 1: |
| #acl GruppoAdmin:admin,read,write,revert -All:read -Known:read | #acl GruppoAdmin:admin,read,write,revert GruppoEditori:read,write,revert -All:read -Known:read #LANGUAGE it [[BR]] ||<tablestyle="font-size: 0.9em; width:35%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;">'''Indice'''[[BR]] [[TableOfContents]]|| ##in questo caso preferisco l'indice qui a sinistra = Guida di stile per la documentazione = = Introduzione = 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 fornisce anche degli standard da usare per i termini più comuni. 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 == * 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. * Scrivere in modo neutrale: non aggiungere commenti personali a riguardo di ciò di cui si sta parlando. * Quanto più è possibile, usare degli esempi espliciti piuttosto che descrivere dettagliatamente una procedura. == Come scrivere == * Scrivere in modo impersonale, non rivolgendosi mai all'utente finale, restando sempre neutrali. * Evitare commenti umoristici, sarcastici o personali, possono distrarre l'utente. * Evitare commenti riguardo il programma e il suo futuro sviluppo, è necessario scrivere riguardo a ciò che si ha davanti agli occhi. == 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. = 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] È buona norma attenersi strettamente a questi modelli nel creare una nuova guida. ||<tablestyle="text-align: justify; width:100%; " style="border:none;" 5%>[[Immagine(Icone/Piccole/note.png,,center)]] ||<style="padding:0.5em; border:none;">''Quando si sta per creare nuova guida, nella pagina vuota è presente una tabella in cui sono elencati i modelli disponibili. In base alla guida che si vuole creare, fare clic sul nome del modello corrispondente.'' || == Struttura del documento == Nella presentazione delle informazioni, è buona norma numerare i passi descritti. 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 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]]|| }}} ||<tablestyle="text-align: justify; width:100%; " style="border:none;" 5%>[[Immagine(Icone/Piccole/note.png,,center)]] ||<style="padding:0.5em; border:none;">''È preferibile non scendere al di sotto del livello due per i titoli delle sezioni rappresentate nell'indice.'' || == 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. Per informazioni su come scrivere i titoli delle sezioni, consultare [#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] }}} ||<tablestyle="text-align: justify; width:100%; " style="border:none;" 5%>[[Immagine(Icone/Piccole/note.png,,center)]] ||<style="padding:0.5em; border:none;">''Prima di tradurre un documento che non sia contenuto nel wiki internazionale è necessario informarsi riguardo la licenza con cui è distribuito. Non tutte le licenze sono compatibili con quella utilizzata da questo wiki.'' || = 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. == Maiuscole e minuscole == ##copiare quella del wiki == Impersonale == Nello scrivere una guida va utilizzata una forma il più impersonale possibile, non rivolgendosi mai all'utente, ma mantenendo un tono neutro. ##mettere in una tabella e magari aggiungere altri esempi Errato Per spostare il file, scrivi... Scegli Salva dal menù... Corretto Per spostare il file, scrivere... Scegliere Salva dal menù... È anche necessario non personificare l'hardware o il software, evitando di "far parlare" o agire il programma in prima persona. ||<tablestyle="text-align: justify; width:100%; " style="border:none;" 5%>[[Immagine(Icone/Piccole/note.png,,center)]] ||<style="padding:0.5em; border:none;">''Le guide relative ai giochi, essendo l'ambito più "amichevole", non devono essere necessariamente impersonali.'' || == 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"). == 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. ##trovarne altre da aggiungere = 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 == ##copiare quella del wiki == Riferimenti all'interno di file == ##copiare quella del wiki == Nomi dei pacchetti di installazione == #copiare quella del wiki == Formato dei file (estensioni) == ##copiare quella del wiki == Nomi dei programmi == ##copiare quella del wiki == Navigazione dei menù == ##copiare quella del wiki... == Navigazione all'interno di un documento == ##copiare quella del wiki, aggiungendo di indicare nel riferimento il nome esatto della sezione a cui si fa riferimento. == Comandi dal terminale == ##copiare quella del wiki == Indirizzi internet == ##copiare quella del wiki == Note, avvisi e suggerimenti == ##copiare quella del wiki == 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. 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. ##copiare il resto dal wiki, aggiungendo che se si deve mettere uno screenshot anche della scrivania, lo sfondo deve essere quello predefinito. Nel caso in cui si vogliano usare delle immagini, tenere a mente queste semplici 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 tenute aggiornate con i nuovi rilasci dell'applicazione. ---- CategoryComunita |
IndiceBR TableOfContents |
Guida di stile per la documentazione
Introduzione
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
- 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.
- Scrivere in modo neutrale: non aggiungere commenti personali a riguardo di ciò di cui si sta parlando.
- Quanto più è possibile, usare degli esempi espliciti piuttosto che descrivere dettagliatamente una procedura.
Come scrivere
- Scrivere in modo impersonale, non rivolgendosi mai all'utente finale, restando sempre neutrali.
- Evitare commenti umoristici, sarcastici o personali, possono distrarre l'utente.
- Evitare commenti riguardo il programma e il suo futuro sviluppo, è necessario scrivere riguardo a ciò che si ha davanti agli occhi.
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.
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]
È buona norma attenersi strettamente a questi modelli nel creare una nuova guida.
Quando si sta per creare nuova guida, nella pagina vuota è presente una tabella in cui sono elencati i modelli disponibili. In base alla guida che si vuole creare, fare clic sul nome del modello corrispondente. |
Struttura del documento
Nella presentazione delle informazioni, è buona norma numerare i passi descritti. 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 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]]||
È preferibile non scendere al di sotto del livello due per i titoli delle sezioni rappresentate nell'indice. |
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.
Per informazioni su come scrivere i titoli delle sezioni, consultare [#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]
Prima di tradurre un documento che non sia contenuto nel wiki internazionale è necessario informarsi riguardo la licenza con cui è distribuito. Non tutte le licenze sono compatibili con quella utilizzata da questo wiki. |
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.
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.
Maiuscole e minuscole
Impersonale
Nello scrivere una guida va utilizzata una forma il più impersonale possibile, non rivolgendosi mai all'utente, ma mantenendo un tono neutro.
- Errato Per spostare il file, scrivi... Scegli Salva dal menù... Corretto Per spostare il file, scrivere... Scegliere Salva dal menù...
È anche necessario non personificare l'hardware o il software, evitando di "far parlare" o agire il programma in prima persona.
Le guide relative ai giochi, essendo l'ambito più "amichevole", non devono essere necessariamente impersonali. |
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").
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.
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
Riferimenti all'interno di file
Nomi dei pacchetti di installazione
#copiare quella del wiki
Formato dei file (estensioni)
Nomi dei programmi
Navigazione dei menù
Navigazione all'interno di un documento
Comandi dal terminale
Indirizzi internet
Note, avvisi e suggerimenti
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.
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.
Nel caso in cui si vogliano usare delle immagini, tenere a mente queste semplici 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 tenute aggiornate con i nuovi rilasci dell'applicazione.
