From 47cc65029ade32cde3b643c127a2253da326ae98 Mon Sep 17 00:00:00 2001 From: ru ru Date: Mon, 4 May 2020 23:40:18 +0100 Subject: [PATCH] docs: create doc/wiki-style-guide --- it/doc/wiki-style-guide.md | 193 +++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 it/doc/wiki-style-guide.md diff --git a/it/doc/wiki-style-guide.md b/it/doc/wiki-style-guide.md new file mode 100644 index 0000000..d84023f --- /dev/null +++ b/it/doc/wiki-style-guide.md @@ -0,0 +1,193 @@ +--- +title: Guida allo stile del wiki +description: +published: true +date: 2020-05-04T22:40:16.308Z +tags: documentation, wiki +--- + +# Guida allo stile del wiki + +## Linee Guida Generali +La seguente sezione offre linee guida sia per la composizione delle frasi, sia per l'uso della sintassi. +Segui queste linee guida per assicurarti che il tono dei tuoi documenti sia coerente con quello del resto della documentazione di OpenMandriva. + +### Composizione + +#### Voce +Per le istruzioni e le regole usa la *voce attiva*, presenta con confidenza al lettore senza sembrare troppo esigente. +L'uso della voce attiva fornisce una direzione chiara. Dice al lettore ciò che fare e da i risultati sperati. +La voce attiva lascia al lettore l'impressione che un'autore sia dietro al lavoro scritto. + +#### Evita la voce passiva a meno che non sia necessario +La *voce passiva* è completamente corretta dal punto di vista grammaticale, però è una barriera per la comprensione da parte del lettore. +La voce passiva inverte la struttura della frase convenzionale. Muove il verbo e il complemento oggetto nella prima parte della frase e posiziona il soggetto nella seconda parte della frase. Spesso una semplice revisione della struttura della frase basta per trasformare una frase passiva in una attiva. +Le frasi passive lunghe e complesse devono spesso essere lette più volte prima che il lettore ne capisca completamente il significato. + +`ATTIVA: Scegli una password forte per migliorare la sicurezza personale.` + +`PASSIVA: La sicurezza personale è migliorata dalla selezione di una password forte.` + +#### Contesto + +Evita di scrivere fuori contesto. +Aderisci attentamente ciò di cui tratta il documento, capitolo, sezione e paragrafo. +Usa referenze appropriate, struttura i documenti in modo che nuove parti vengano costruite su quelle vecchie. +Evita che il lettore salti qualcosa per mettere le parti in un contesto. +Fornisci dei link ad altra documentazione se il lettore dovesse avere bisogno di ulteriori chiarimenti. + +#### Enfasi + +L'enfasi è molto efficace quando non è usata frequentemente. +Usa metodi di enfasi come il grassetto, la sottolineatura o il testo obliquo per attirare l'attenzione su un termine specifico. +Usa esortazioni per evidenziare materiale rilevante. +Un'altra maniera accettabile per enfatizzare un punto è variare la formazione della frase o la scelta delle parole. +I migliori autori di documentazione pianificano l'uso dell'enfasi, applicandola con costanza in tutto il documento. + +#### Precisione e Esattezza + +La precisione e l'esattezza fanno la diffenza in un documento. +Questo assioma comprende sia la precisione tecnica che la precisione letterale. +Scegli parole dopo aver tenuto in considerazione più situazioni d'uso possibili. Per esempio "vai a" non è preciso come "clicca", però "clicca" potrebbe non essere accurato per tutti i tipi di interfaccia. Il termine "seleziona" è corretto in ogni situazione con precisione sufficiente. +Non preoccuparti troppo nel tentare di coprire tutte le potenziali situazioni d'uso. Il fatto di coprire casi rari allunga il documento senza motivo e il lettore nel frattempo perde la concentrazione. + +#### Tempo Verbale + +Il tempo verbale è il tempo nel quale il linguaggio prende forma. +Ci sono tre tipi principali di tempo verbale: passato, presente e futuro. Seleziona un tempo appropriato a cui il documento deve aderire. +Per quanto riguarda la documentazione tecnica usa il tempo presente ovunque sia possibile usarlo. +Mantenere lo stesso tempo verbale per ogni frase in un documento è vitale perchè esso sia chiaro. +Usa sempre lo stesso tempo verbale per la spiegazione di tutte le fasi di una procedura. + +## Utilizzo + +### Contrazioni + +Evita di usare contrazioni, la combinazione di due parole con un apostrofo che rimpiazza una o più lettere. +Le contrazioni riducono la leggibilità dei documenti e rendono la traduzione più difficile. +Culture e lingue diverse potrebbero interpretare le contrazioni in maniera differente e questa confusione è in contrasto con lo scopo del progetto Documentazione di OpenMandriva. + +### Pronomi + +I pronomi sono parole che una lingua usa per sostituire certi nomi in una frase. +I buoni scrittori devono trovare un punto d'equilibrio tra il ripetere troppe volte una frase nominale e usare i pronomi per sostituire i nomi. Una regola generale per preservare la chiarezza è quella di non ripetera mai la sostituzione dei nomi con pronomi in due frasi consecutive. +I lettori di documentazione tecnica devono avere dei riferimenti costanti a quale sia il soggetto esatto a cui l'autore si sta riferendo. L'uso eccessivo di pronomi può portare il lettore a dover indovinare il soggetto a cui una frase si sta riferendo. +Questi presupposti riducono l'efficacia della documentazione. + +Evita la maggior parte dei pronomi personali nella documentazione, inclusi i seguenti: +* Pronomi personali soggetto ("Io", "lui", "lei", "noi", "voi") +* Pronomi personali oggetto ("mi", "le", "gli", "ci") +* Pronomi personali possessivi ("mio", "suo", "nostro") + +Evita anche: +* Pronomi rafforzativi come "lui stesso" o "tu fattelo da solo" +* Resisti all'uso eccessivo di "tu", "tuo" e "di qualcuno" + +Occasionalmente certe situazioni richiedono l'utilizzo del pronome "tu" e forme affini perchè la frase risulti chiara. +Mantenere l'uso della voce attiva è fondamentale per evitare i pronomi personali. "Tu" e "tuo" sono parole appropriate per indicare azione o possesso da parte del lettore. +I pronomi indefiniti come "questo" o "quello" senza nulla davanti rendono difficile per il lettore seguire ciò che l'autore intende esprimere. +Favorisci la scrittura di una frase con un nome preciso quando possibile invece di utilizzare parole vaghe come "questo", "quello" e affini. + +`SCORRETTO: Edita i tuoi file di configurazione di yum per usare mirror più vicini geograficamente. Questo ti permette di aggiornare il tuo sistema più velocemente.` + +`CORRETTO: Edita i file di configurazione di yum per usare mirror geograficamente vicini in modo da aggiornare il sistema più rapidamente.` + +Quando si eliminano i pronomi indefiniti una frase lunga e farraginosa potrebbe essere causata da troppe proposizioni. +Usa pronomi indefiniti per spezzare frasi lunghe per migliorare la chiarezza, ma fornisci sempre degli antecedenti appropriati. + +`SCORRETTO: Stai al passo con gli aggiornamenti raccomandati per il tuo sistema operativo in modo da migliorare le funzionalità delle applicazioni, rimuovere rischi di sicurezza e risolvere automaticamente problemi di prestazione risolti a partire da segnalazioni di bug.` + +`CORRETTO: Stai al passo con gli aggiornamenti per il tuo sistema operativo. +Questi aggiornamenti migliorano le funzionalità delle applicazioni, rimuovono rischi di sicurezza e aggiustano automaticamente i problemi di performance aggiustati a partire da segnalazioni di bug.` + +### Formazione della frase + +Scrivi frasi che siano il più corte possibile. +Eliminare parole non necessarie è vitale per rafforzare il significato. +Ci sono svariate trappole per gli scrittori di documentazione tecnica con il risultato di lunghe frasi. + +#### Discorso Indiretto + +Il discorso indiretto si riferisce all'uso di "quello" per attribuire un affermazione, fatto o sentimento in una frase senza l'uso di un punto di domanda. +Nella scrittura normale indebolisce le affermazioni di fatto. +Gli scrittori di documentazione possono migliorare l'impatto delle frasi rimuovendo "quello" e "quale". + +`SCORRETTO: Mandriva è un sistema operativo open source che è fonte per tanti altri progetti opensource.` + +`CORRETTO: Mandriva è un sistema operativo open source fonte di molti altri progetti open source.` + +#### Altre Combinazioni di Parole non Necessarie + +Evita l'utilizzo di parole non necessarie come la parola "quindi" seguita da una fare con il se. +Quando una frase inizia con "se", alla fine della frase metti una virgola e completa la frase con un'affermazione. + +`SCORRETTO: Se un client e-mail non riceve o manda messaggi, quindi controlla sotto il menù file e verifica che la modalità "Lavoro Offline" non sia selezionata.` + +`CORRETTO: Se un client e-mail non riceve o manda messaggi, controlla sotto il menù file e verifica che la modalità "Lavoro Offline" non sia selezionata.` + +Tante parole che usiamo nella conversazione quotidiana riducono l'impatto su materiali stampati perchè "lasciano una via d'uscita". +Queste sono parole che precedono verbi e nomi per minimizzare l'influenza della frase. Questa non è una lista esaustiva ma, scrittori di documentazione responsabili ridurrebbero l'utilizzo di queste parole e di altre parole di natura simile. + +#### Evita le Parole Inutili che Riducono l'impatto +Le seguenti parole minimizzano l'impatto del verbo o predicato nominale in una frase. +Altre parole entrano anch'esse in questa categoria, ma questa breve lista ha lo scopo di aiutare coloro che scrivono la documentazione a eliminare queste parole dal loro modo di scrivere: **dovrebbe, potrebbe, forse, qualche, tanti, la maggior parte, pochi, in quache maniera, possibilmente, può occasionalmente e frequentemente**. + +#### Variazioni alla Frase +Per avere l'impatto più forte, tieni la prima e l'ultima frase di un paragrafo il più corte possibile. +Cambiare la lunghezza della frase all'interno di un paragrafo e lungo l'intero documento tiene alta l'attenzione del lettore. +Un fatto corto e semplice è facile da capire e usare per analizzare la materia della frase successiva. +Non c'è nulla di male nell'usare frasi più lunghe per spiegare idee e concetti complessi. Prova ad utilizzare una semplice frase riassuntiva alla fine di ogni paragrafo per dare ai lettori un piccolo ripasso delle informazioni importanti. +Una breve frase finale accompagna il lettore alla sezione successiva. + +#### Lettere Maiuscole +Nelle frasi metti la maiuscola alla prima parola. +Non iniziare frasi con un comando, pacchetto o opzione. + +`SCORRETTO: smolt fornisce il profiling dell'hardware.` + +`CORRETTO: Il pacchetto smolt fornisce il profiling dell'hardware.` + +ùùùùùùùùùùùùùùùù + + + +#### Punteggiatura +La punteggiatura è un componente cruciale per la comprensione del testo. +Una virgola messa al posto sbagliato oppure un segno di punteggiatura possono cambiare interamente il significato della frase. +I segni di punteggiatura sono i fissaggi nella cassetta degli attrezzi dello scrittore. I lettori sono abbituati ai regolari chiodi e viti, come virgole e punti. Inizia a usare segni di punteggiatura non comuni come punto e virgola, puntini di sospensione o quei segni non familiari e il lettore probabilmente si distrarrà facilmente. +Segni di punteggiatura complessi non sono universali e ostacolano gli sforzi per tradurre la documentazione di OpenMandriva. + +Riduci al minimo l'utilizzo di questi segni di punteggiatura nella documentazione: +* Parentesi +Per compensare riformula la frase, oppure rompila in due pensieri completamente diversi. +* Punto e virgola +Buoni da usare solo se due pensieri sono correlati, devono essere collegati per chiarezza o per rimuovere il bisogno di utilizzare una congiunzione. +* Due Punti +Se c'è una lista con più di tre elementi, usa un elenco puntato per facilitare la comprensione. +* Puntini di Sospensione +Non usarli per motivi di enfasi stilistica... solo per dare rilievo a una continuazione indefinita del contenuto in un esempio. +* Punti Esclamativi +Nella scrittura tecnica sono accettati solo per segnalare un pericolo e non per dare enfasi a qualcosa. +* E Commerciale +Le parole "and" o "e" devono essere scritte per intero, questo carattere si può utilizzare solo se parte di un comando da digitare nel computer. +* Slashes +Non usare gli slash come versione accorciata di "lui o lei" usando lui/lei, usa invece le parole "e", "o" oppure "entarambi". Gli slash sono comunemente utilizzati nei percorsi dei file e usarli in altro modo potrebbe creare confusione. + +## Altre Domande sulla Scrittura +Ogni scrittore incontra i suoi ostacoli. Diventa difficile metter in una frase qualcosa, oppure le parole "non suonano bene". +Per questo motivo il progetto OpenMandriva è un lavoro di squadra. Contatta gli scrittori della documentazione nella mailing list o nella chat per aiutarli con le parole oppure con la forma del testo. +Un altro trucco professionale che gli scrittori usano quotidianamente è quello di stare lontani dal progetto per qualche tempo. Prenditi una pausa dalla scrittura del documento. Ritornare su un punto critico con occhi freschi è spesso ciò che serve per superare gli ostacoli nella scrittura. + +Lo scopo generale del Progetto di Documentazione di OpenMandriva è quello di fornire assistenza agli utenti di OpenMandriva in un linguaggio facile da capire. +Non devi scrivere per impressionare un professore di italiano, oppure per mostrare la tua destrezza in una determinata materia. Frasi corte, definizioni frequenti di termini strani e link a pagine di aiuto aggiuntive sono gli aiuti preferiti dalla nostra audience. +Scrivi con il tuo obiettivo in mente e la tua documentazione sarà la più visitata dagli utenti che hanno bisogno di risposte. + + +*Crediti: +Tratto da* [Fedora Project Style Guide](http://Fedoraproject.org/wiki/Docs_Project_Style_Guide_-_General_Guidelines) + +---- +## Stile specifico per il wiki di OpenMandriva +Leggi anche [OpenMandriva wiki specific style guide](/en/doc/omawiki-style-guide) + +