194 lines
13 KiB
Markdown
194 lines
13 KiB
Markdown
|
---
|
||
|
|
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: <code>smolt</code> fornisce il profiling dell'hardware.`
|
||
|
|
|
||
|
|
`CORRETTO: Il pacchetto <code>smolt</code> 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)
|
||
|
|
|
||
|
|
|