Good Docs - Il punto di vista di un traduttore
Introduzione¶
I traduttori forniscono indicazioni preziose per la stesura di una documentazione chiara e concisa. Sanno cosa non si traduce bene e cosa confonde il lettore meglio di chiunque altro. Questo documento esamina alcuni di questi aspetti ed evidenzia le migliori pratiche per la stesura dei documenti.
Dall'autore¶
La documentazione del software aiuta gli utenti a capire come utilizzare efficacemente un determinato software. Devono capire cosa otterranno alla fine e quali vantaggi avranno. Allo stesso tempo, quando create una documentazione, significa crearla non solo per voi stessi, ma anche per la vostra rete e per le altre persone che potrebbero leggerla. Gli altri utenti potrebbero non provenire da paesi anglofoni. Ciò significa che per loro l'inglese non è la lingua principale. Proprio per questo motivo, seguite queste regole di base per rendere la documentazione più leggibile a tutti gli utenti.
Uso di un linguaggio semplice¶
In linea di principio, non si ha idea di chi siano i fruitori della documentazione. Se l'utente abbia o meno familiarità con questo ambito, che sia uno sviluppatore esperto o un principiante. Un linguaggio semplice sta a significare una comunicazione chiara, concisa e di facile comprensione per il pubblico a cui è destinata la prima volta che la incontra. E' da evitare i termini gergali, quelli troppo tecnici e frasi con strutture complesse, a favore di un linguaggio più semplice e con un'organizzazione chiara. L'obiettivo è garantire che il messaggio sia accessibile e comprensibile a un ampio pubblico, indipendentemente dal suo background o dal suo livello di lettura. Spesso è possibile farlo semplificando la sintassi delle frase o i comandi fino ad una forma più elementare.
Evitare espressioni idiomatiche, gergo, acronimi e contrazioni.¶
Idiomi, gergo, contrazioni e acronimi possono confondere i lettori che non li conoscono, in particolare coloro che non sono madrelingua, i nuovi dipendenti o tutti coloro che estranei al vostro settore specifico.
I diomi sono spesso culturalmente specifici e possono essere difficili da capire per i lettori internazionali.\ Il gergo comprende termini specialistici che solo gli esperti di un settore possono riconoscere.\ Le contrazioni sostituiscono le parole della lingua inglese con scorciatoie, che però non sempre esistono in tutte le lingue, rendendo difficile la traduzione.\ Gli acronimi possono essere ambigui, soprattutto se non vengono definiti al momento del loro utilizzo.
Esempio:
❌ “Una volta presa confidenza con il cruscotto, il resto è un gioco da ragazzi”. In questo caso, l'autore utilizza sia una contrazione, sia uno slang, sia un idioma.
✅ “Una volta imparato a usare il cruscotto, il resto è facile”. Sostituendo la contrazione, il gergo e l'idioma con le parole associate a ciascuno di essi, il significato è chiaro.
Il linguaggio figurato, come i modi di dire, spesso non si traduce bene. I redattori tecnici o i traduttori potrebbero avere difficoltà a trasmettere lo stesso significato in altre lingue.
Esempio:
❌ “Ci sentiamo la prossima settimana per fare il punto sui ticket aperti”.
✅ “Incontriamoci la prossima settimana per rivedere le richieste di supporto non risolte”.
Il gergo e gli acronimi possono generare confusione, anche all'interno della stessa organizzazione, se il loro significato non è universalmente conosciuto.
Esempio:
❌ “Caricare il CSV nel CMS ed etichettarlo secondo le SOP”.
✅ “Caricare il file CSV (Comma-Separated Values) nel Content Management System (CMS) ed etichettarlo secondo le procedure operative standard (SOP).”
Nota: se si desidera utilizzare acronimi, definirli sempre la prima volta: “Content Management System (CRM)”.
Eliminando i modi di dire e il gergo non necessario, il significato del documento diventa più chiaro. Sostituire le contrazioni con le parole che rappresentano significa facilitare gli sforzi di traduzione in tutte le lingue. Il documento è più comprensibile per il lettore quando si sostituiscono o si definiscono gli acronimi.
Uso della forma attiva¶
La voce attiva enfatizza chi compie l'azione, rendendo chiaro chi o cosa è responsabile dell'azione del verbo.
Esempio:
Il sistema apre la finestra di dialogo in cui è necessario completare il modulo.
Si prega di astenersi dall'utilizzare una forma complessa, in quanto può confondere i lettori.
Per saperne di più sull'uso della forma attiva e sulla sua importanza, si veda questa parere e questa fonte esterna.
Dividere in step¶
Se la documentazione contiene passaggi specifici, separateli l'uno dall'altro.
Ad esempio:
Passo 1 - Accedere alla sezione Passo 2 - Fare clic sul pulsante Passo 3 - Compilare il modulo ...\ Passo N - salvare le modifiche
Screenshot quando necessario¶
Utilizzate screenshot corretti dove necessario. Ciò significa che non è necessario aggiungere screenshot ovunque, ma solo nei punti in cui è necessario fornire ulteriori spiegazioni.
Uso degli esempi¶
Se è necessario compilare il modulo, fornire esempi di come gli utenti possono completarlo. Indicare le limitazioni, se ci sono.
Conclusione¶
Scrivere una buona documentazione non significa solo renderla tecnicamente accurata, ma anche renderla immediatamente comprensibile al lettore. Questo è particolarmente importante quando un documento tecnico deve essere tradotto in altre lingue. In questo documento, l'autore intendeva mettere in evidenza le tecniche specifiche per scrivere una buona documentazione chiara.
Author: Ganna Zhyrnova
Contributors: Steven Spencer