Lingua e stile

Lingua
Stile

Dopo il fiume di informazioni delle sezioni precedenti, si può volgere lo sguardo ad altri aspetti importanti nello scrivere la documentazione: la lingua e lo stile (in questa sezione) ed i diritti d'autore (nella successiva sezione).

Lingua

La comunità di Firebird è molto variegata, e costituita da persone di diversa lingua madre. Scrivendo il documento in una lingua diversa dalla propria, è possibile fare errori. Ciò non è catastrofico, ma almeno bisogna cercare di ridurre al minimo tali errori. Si possono adottare alcune strategie per aiutarsi nel compito:

Usare un dizionario! Semplice, efficace, e felicemente non tecnologico.
Essendo incerti sulla scrittura di una parola, o fra diverse possibili versioni di un modo di dire, si può cercare in rete fra le alternative e controllate le frequenze. Magari seguendo i link dei risultati della ricerca per vedere come viene usata la parola o l'espressione nella lingua viva.
Far controllare il vostro testo da qualcuno di lingua madre e correggetelo ove necessario.

Stile

Questa non è una vera e propria guida sullo stile, perchè non saprei proprio come scriverne una. Solo alcune linee guida e suggerrimenti:

Cercare di scrivere col semplice linguaggio di ogni giorno, ovunque possibile. Evitare le parole difficili se esiste un'alternativa più usuale e familiare.
Evitare le frasi lunghe (oltre le 25 parole) se possibile; specialmente evitare due frasi molto lunghe una dopo l'altra.
(N.d.T. tradotto letteralmente; è bene leggere i suggerimenti per le traduzioni in italiano qui sotto) Fare attenzione ai costrutti con doppie e triple negazioni («Non posso negare che non mi dispiace») e le voci passive («Attenzione deve essere fatta...»). Non è che sono da evitare ad ogni costo, ma possono rendere una frase più difficile da capire. Nel caso eliminare le doppie negazioni («Sono compiaciuto») e usare una voce attiva («Fate attenzione...»).
Usare liste per elencare un certo numero di oggetti in serie, ad esempio:
- Un insieme di suggerimenti e trucchetti.
- Una serie di esempi (come questo).
- Passi da seguire in una procedura.
- Soluzioni alternative ad uno stesso problema.
Nel caso ci fossero solo un esiguo numero di termini brevi, invece è meglio usare una frase lineare come: «Mia madre ama tre uomini: John, Dick, e Dave.»
È meglio non adoperare troppi punti esclamativi o punti di domanda. Sono proprio brutti!!!!! Non siete d'accordo???
Per i traduttori dall'inglese in italiano - aggiunto nella sola versione italiana: Basandomi sulla mia (invero misera) esperienza, le linee guida che posso dare a chi si accingerà ad aiutarmi a tradurre dall'inglese in italiano questi manuali, si basano su queste poche note. Ricordarsi che la seconda persona plurale inglese non è consigliabile tradurla letteralmente (troppo colloquiale): in italiano esistono varie alternative. Usare ad esempiol'infinito: («Use lists to enumerate» diventa «Usare le liste per elencare»), oppure una frase impersonale («Don't overuse exclamation marks» si può tradurre con «È meglio non adoperare troppi punti esclamativi»). Altre volte aiuta il gerundio («If you write your documentation» eccolo tradotto in «Scrivendo il documento»). Altra cosa difficile da evitare in un buon italiano sono le rime: meno ce ne sono, migliore e più leggibile risulta il testo; provare per credere. Le rime possono essere in fine parola ma anche all'inizio, e sono più difficili da stanare: si trovano rileggendo ad alta voce. Confrontando questo documento in inglese ed in italiano, si possono trovare anche altre soluzioni: talvolta è stato necessario girare o cambiare tutta una frase perchè una sua traduzione troppo letterale non mi «suonava» proprio.

Il blocco dello scrittore.

Talvolta si conosce quello che che si vuol dire, e ci sono anche le parole giuste, ma non si riesce a cominciare la frase: proprio non si riesce a farle andare. È veramente frustrante e può proprio bloccare il procedere del testo per molti minuti. E la frustrazione risulta ancora maggiore sapendo cosa si vuol dire ai lettori, ma apparentemente non si è in grado di scrivere una frase decente. Dopo una serie di esperienze da panico, ho sviluppato la seguente strategia (anche se non credo di essere stato il primo):

Scrivere ciò che si deve dire in frasi sparse e frammentarie senza preoccuparsi né dello stile né che il tutto potrà sembrare orrendo. Scrivere proprio quello che si deve dire al lettore ed assicurarsi che ci sia tutto e nel giusto ordine. Se si nota, facendo questo, di essere insicuri di qualcosa, evidenziarlo proprio in quel punto. Fatelo in modo che escano dal testo intorno, ad esempio <<tipo questo>> oppure !QUALCOSA DEL GENERE!

Questo può trasformare il testo in qualcosa come:

CVS significa Concurrent Versions System (<<controllare!>>). Obiettivo: gestire le versioni del software. Si può usare da soli o in gruppo. Ci vuole un client CVS per usarlo. Un client CVS è un programma con cui si accede ad una repository (<<spiegare il temine?>>) di un CVS. Per sapere se un CVS è installato nel proprio sistema, digitare «cvs» sulla linea di comando. Se non c'è, vai a questo sito per scaricarlo ... [ecc., ecc.]
Gestire prima ogni cosa in evidenza. Cioè Controllare se CVS davvero significa Concurrent Versions System (giusto). Decidere se davvero conviene spiegare il termine «CVS repository» a quel punto (e si dovrebbe farlo).
A questo punto, ripassando il paragrafo, provare a rendere il testo più scorrevole dovunque possibile. Ci sono possibilità che sia molto più facile del previsto!
Se sembra ancora un po' grezza, non importa: meglio grezza e chiara che scoordinata ed incomprensibile. Magari, non si sa mai, ripassandoci in un secondo tempo, si riesca a renderla più carina.

Questo sistema per me funziona bene e. come si dice, bloccandovi qualcosa, «tentar non nuoce».