Tema e struttura dell’articolo

Prediligete gli argomenti in cui siete esperti

La “prima legge della comunicazione” di Whittington (annoverata tra le famose leggi di Murphy) afferma che “quando qualcuno spiega un argomento che non ha ben capito, sarà compreso solo da chi ne sa più di lui”.
Avere una profonda conoscenza di un argomento aiuta a non commettere errori, che comprometterebbero l’immagine dell’autore e dell’editore. Aiuta a scegliere gli aspetti più interessanti da trattare, perché vengono automaticamente suggeriti dall’esperienza personale e dagli errori maturati col tempo. Infine aiuta a scrivere meglio, a scegliere le parole giuste, gli esempi più efficaci, il filo logico più chiaro.

Definite il vostro obiettivo

Un articolo deve avere un obiettivo: dimostrare, risolvere, chiarire, spiegare, inquadrare.
Tenete sempre presente il vostro obiettivo durante la stesura del testo e se non è chiaro dal titolo, specificatelo nell’introduzione.
Se il percorso da intraprendere è complicato e richiede molte “tappe”, anticipatelo al lettore e a ogni passo ricapitolate cosa avete fatto e cosa state per fare per arrivare alla “meta”. 
Il lettore deve capire in ogni momento da dove è partito, dove arriverà e dove si trova.

Scrivete titolo, occhiello e abstract efficaci

Una delle difficoltà più comuni tra gli autori alle prime armi è dare all’articolo una struttura chiara ed efficace.
A grandi linee, tutti gli articoli tecnici sono formati da un’introduzione, un corpo (suddiviso in vari paragrafi) e una conclusione. Tuttavia molti non riescono a sfruttare al meglio questa suddivisione e a distribuirvi i contenuti in maniera equilibrata.

L’introduzione serve a “sedurre” il lettore e a promettere che la fiducia accordata sarà ripagata nel resto dell’articolo. 
Se non sapete come cominciare, provate a chiedervi: “Qual è il problema che questo articolo risolve? Alla fine dell’articolo il lettore cosa avrà imparato?” e utilizzate le risposte per modellare un’introduzione efficace.
Non è detto che l’introduzione debba essere scritta per prima. Anzi, spesso è scritta a lavoro terminato, quando si hanno le idee più chiare su come sono articolati i contenuti.
Gli stessi princìpi si applicano all’occhiello o all'abstract, quando sono previsti nell’articolo o nel documento. 
L’occhiello serve prevalentemente per attirare l’attenzione del lettore (in due o tre righe) e convincerlo ad “immergersi” nella lettura. 
L’abstract è il semplice riassunto dell’articolo: ne concentra contenuto e conclusioni.

Inoltre, introduzione, occhiello ed abstract sono gli elementi immediatamente visibili nel browser: da qui la loro importante funzione persuasiva.

Vediamo un esempio tratto da un mio articolo di qualche anno fa:

occhiello
L’MCI di Windows consente di riprodurre suoni e animazioni all’interno della propria applicazione. Nell’articolo viene mostrato come sfruttare queste funzioni API creando una comoda classe di interfaccia.

titolo
Suoni e animazioni in applicazioni VB 

abstract
Capita spesso di dover riprodurre nella propria applicazione un suono o un’animazione associata a un evento (come la pressione di un pulsante) o durante l’esecuzione di una routine (come la copia di un file). In Visual Basic sono disponibili vari controlli, anche forniti da terze parti e freeware, che svolgono questa funzione, ma talvolta può essere eccessivo includere un OCX al progetto.
Possiamo, con la stessa quantità di codice necessaria alla gestione del controllo, agire sulla Multimedia Control Interface (MCI) di Windows. Alla lunga però può essere ripetitivo e quindi noioso occuparsi delle varie fasi quali l’inizializzazione, l’esecuzione, la gestione degli errori, e così via: in quest’articolo verrà spiegato come creare una classe VB che gestisce la riproduzione di file multimediali avi, wav e mid semplificando notevolmente la vita del programmatore e alleggerendo il programma da OCX superflui.

(da Computer Programming 76 del gennaio 1999)

L’articolo è stato pubblicato su una rivista informatica di programmazione, quindi il tipo di lettore era ben definito. Avrete sicuramente notato come il lessico sia molto settoriale. Dato che l’articolo è di livello medio, già nell’occhiello si danno per scontati i concetti di MCI, Windows, applicazione, API, classe. Più avanti vedremo l’esempio opposto, in cui il pubblico è quello di un quotidiano e data la sua eterogeneità non è possibile dare niente per scontato.

In questo caso, già il titolo fa già capire di cosa tratta l’articolo. L’occhiello “rincara la dose”, spiegando l’obiettivo (riprodurre suoni e animazioni nei programmi). Notate l’aggettivo “comoda” che enfatizza un beneficio derivante dalla lettura. Infine l’introduzione spiega il problema e anticipa la soluzione e i vantaggi (notate i verbi “semplificare” e “alleggerire”).  

Utilizzate un approccio top-down

Il corpo del testo deve essere suddiviso in paragrafi.
Una forma di organizzazione standard, utile per chi inizia e da sempre efficace negli articoli tecnici è quella top-down, cioè “dal generale al particolare”. 
Iniziate spiegando le linee generali del vostro argomento in un paragrafo; in quelli successivi approfondirete le sottoparti dell’argomento, uno per paragrafo. 
Alla fine non deve mancare un esempio pratico (in un articolo che spiega la teoria dei colori e come migliorare le tonalità di una foto, il lettore si aspetta un esempio pratico di intervento su foto reali).

Il metodo top-down garantisce ottimi risultati con i lettori principianti (che sono introdotti gradualmente nei dettagli) ed è sempre gradito ai lettori esperti, che con l’occasione possono ripassare un argomento e comunque possono facilmente saltare dalla parte generale ai dettagli.

I contenuti

Esaustivi, ma non troppo

Stabilite fin dall’inizio il tipo di lettore a cui vi rivolgete (principiante, medio, esperto). Se non è chiaro dal contesto (molti siti lo indicano in un riquadro), specificatelo nell’introduzione, insieme alla preparazione che il lettore deve avere per comprendere i contenuti.
Durante tutto l’articolo tenete presente il lettore-tipo, cercando di spiegare i concetti che pensate non conosca. Se siete sul web può essere utile fornire link ad altri articoli o siti. Cercate di dare al lettore tutte le informazioni di cui ha bisogno, ma non tutto quello che voi sapete su un certo argomento.
Se l’articolo si rivolge a un pubblico già esperto, potete saltare delle spiegazioni di base, ma assicuratevi di citare qualche riferimento bibliografico (o link) sugli argomenti che saltate, in modo che anche i principianti abbiano l’opportunità di prepararsi prima di leggere l’articolo.

Fatti, non parole

Non distogliete mai l’attenzione dal punto di vista del lettore. 
Chi legge, al termine di ogni paragrafo si chiederà “A cosa serve in pratica? Quali sono i vantaggi? Cosa comporta?”. 
Un articolo ben fatto deve rispondere prontamente a queste domande, anche anticipando le risposte alle domande e ai dubbi del lettore.

È interessante sapere che “Google offre un Web service per interfacciarsi al suo motore di ricerca”. Ma lo sarà ancora di più (e anche per i non addetti ai settore) se spiegherete che “Questo permette di avere un (super) motore di ricerca già pronto da inserire nelle pagine del vostro sito”. Voi sapete che il vostro articolo è straordinariamente utile, ma il lettore no: solo mostrando le applicazioni reali ed esempi pratici riuscirete a convincerlo.

Non importa quanto un argomento sia teorico: esiste sempre una applicazione pratica per spiegarne i vantaggi. Sapevate che Alinghi ha vinto la Coppa America 2003 grazie alle equazioni matematiche della fluidodinamica di Navier-Stokes? 

Usate con intelligenza le figure

Le figure completano il prodotto “articolo”. 
Spesso sono il primo elemento che il lettore nota insieme al titolo.
Cercate di inserirne almeno una: uno schema, una foto del prodotto che state spiegando, una schermata del software che state programmando. “Vedere” di cosa si sta parlando è importante per il lettore, a volte fondamentale per attirare la sua attenzione.
Non dimenticate nemmeno di inserire una didascalia significativa, magari con una spiegazione dei contenuti dell’articolo. Per esempio, in un articolo sull’utilizzo delle macchine fotografiche digitali, una (bella) foto in prima pagina con didascalia

“Non è facile scegliere la giusta apertura di diaframma per le foto. Nell’articolo imparerete come avere il meglio da ogni condizione.”

indurrà sicuramente a leggere.

La struttura di una buona didascalia è semplice: si espone il problema e subito dopo la soluzione, rimandando alla lettura.

Chiarite i concetti con esempi, similitudini e metafore

Indipendentemente dal tipo di articolo che state scrivendo, non dimenticate di fornire puntualmente al lettore esempi pratici che esemplifichino concetti e teorie. 
Questo vale soprattutto per il web: molte volte il lettore non è esperto dell'argomento e se la lettura diventa troppo difficile sarà portato ad abbandonare e cercare un sito più semplice.

Esempi, similitudini e metafore sono gli "arnesi" preferiti dallo scrittore per facilitare la comprensione di concetti. 
Il problema è che per spiegare un concetto ci sono di solito molte alternative, non tutte egualmente efficaci: sta all’autore scegliere la più adatta. 
Tenete presente che una similitudine sbagliata provocherà un effetto contrario: oltre al pericolo di incappare in cadute di stile o di rasentare il ridicolo, potreste scegliere paragoni poco intuitivi (una volta ho letto che “un certo collante era forte come la forza nucleare debole”), che renderanno ancora più difficile la lettura. 

Ecco come Piero Angela spiega il significato di “zero assoluto”:

“Per comprendere il significato di zero assoluto, basta tener predente un concetto molto importante in fisica: il calore è movimento. [...] Se si mette una pentola d’acqua sul fuoco, dopo qualche minuto, si vede che la massa di acqua si muove leggermente, e che si sono create delle piccole correnti. Una volta arrivati a 100 gradi, l’acqua com’è noto si mette letteralmente a bollire.
In un certo senso è in perenne movimento. Se al contrario si raffredda sempre più la pentola, l’acqua rallenta il suo movimento interno, fino a diventare calma e, quando si raggiungono gli zero gradi, si ghiaccia.
A quel punto tutto è immobile. In un certo senso lo stesso accade alla materia. Più un oggetto è caldo, più le molecole che lo compongono si agitano, “vibrano”. E viceversa, più è freddo, più le sue molecole rallentano il movimento. È evidente che questo rallentamento non è infinito: a un certo punto, le molecole a forza di rallentare si fermano del tutto. Oltre non si può andare: le molecole infatti non possono essere più ferme di così.
Proprio come fra vari orologi fermi, non ce n’è uno più fermo degli altri.
Questo è, appunto, lo zero assoluto: la temperatura alla quale tutto è fermo all’interno della materia. Tale temperatura è di -273,15 gradi centigradi.”

(Viaggio nella scienza, supplemento a “la Repubblica”)

In questo caso il pubblico era quello di un quotidiano, quindi eterogeneo: non si poteva dare per scontata nessuna preparazione sull’argomento. 
Ecco perché l’autore ha innanzitutto introdotto il concetto base “il calore è movimento”. E per farlo ha scelto un esempio concreto, quello della pentola che bolle: in questo modo nella mente del lettore prendono forma immagini di situazioni reali di cui ha avuto diretta esperienza e riesce a comprendere per “estrapolazione” i nuovi concetti.
Solo dopo aver formato il lettore con la nozione di base, l’autore spiega il significato di  zero assoluto con una similitudine: “come fra vari orologi fermi, non ce n’è uno più fermo degli altri”.

Ritocchi e revisione finale

Riferimenti bibliografici

La bibliografia è un aspetto da curare con molta attenzione. 
Se consigliate i testi e i siti giusti, il lettore aumenterà la sua stima nei vostri confronti. 
Una bibliografia ben fatta prova che l’autore conosce bene la letteratura su un certo argomento: lo noteranno sia il lettore ia il technical reviewer che revisionerà l’articolo.
Attenzione alla troppa “auto-referenziazione”, cioè all’inserire troppi (e soprattutto non pertinenti) riferimenti ad articoli propri. I riferimenti forzati ottengono l’effetto opposto a quello appena esposto.
La forma dei riferimenti varia a seconda della rivista o del sito.

La revisione

Dopo aver completato l’articolo, lasciate passare qualche giorno prima di rileggerlo e fare la lettura finale. Più tempo passa meglio è, ma è evidente che i tempi editoriali non permettono di aspettare più di tanto.
Se potete, fate leggere l’articolo a uno o più colleghi: avere l’opinione di estranei è utilissimo, sia per trovare errori tecnici, sia per migliorare la struttura e lo stile dei contenuti.

Il parere di un estraneo è essenziale, perché l’autore non riesce a vedere tutti i suoi errori. Gli articoli tecnici devono passare almeno una revisione tecnica da parte di uno o più technical editor o technical reviewer. Tale revisione serve a stabilire se i contenuti sono validi e corretti. 
Passata la revisione tecnica, si passa alla revisione stilistica, per migliorare la forma espositiva. Quest'ultima viene fatta dallo stesso reviewer (soprattutto nel web), oppure da un revisore non tecnico (tutte le riviste hanno un revisore per la lingua e lo stile).

Consegnate l’articolo stilato secondo le norme editoriali fornite dalla rivista o dal responsabile del sito web. Gli editor valutano la professionalità dell’autore non solo in base ai contenuti, ma anche in base alla “forma” dell’articolo, cioè al modo in cui esso è presentato.
Ogni rivista ha le sue norme editoriali, di solito raccolte in un documento che ogni autore può richiedere all’inizio della collaborazione con la casa editrice o con il sito. 
In questo documento sono elencati i caratteri da utilizzare, il formato delle figure, della bibliografia, e così via. A volte c’è allegato un articolo dimostrativo.

Chiedete all’editor le norme editoriali e seguitele alla lettera. Se non esistono, chiedete di avere un articolo di esempio cui ispirarvi. Cercate di usare gli stessi standard e in caso di dubbio (le didascalie vanno incluse sotto le figure? Web si scrive minuscolo o maiuscolo? I termini inglesi vanno in corsivo?) chiedete in anticipo ai responsabili: farete un’ottima impressione dimostrando attenzione ai dettagli.

Imparate dagli errori

Nessun consiglio è migliore dell’esperienza. 
Quando consegnate un articolo, chiedete a chi ha revisionato lo stile di farvi avere una copia delle correzioni. Spesso le revisioni sono inviate in ogni caso, per essere accettate dall’autore.
Se possibile, prima di consegnare l’articolo per la pubblicazione, chiedete all’editor di commentare le revisioni con delle spiegazioni: soprattutto all’inizio e se scrivete in lingua straniera sarà utilissimo per non cadere una seconda volta nell’errore. 
Non c’è cosa peggiore degli autori che ripetono ogni volta gli errori: darete un’impressione di pigrizia e non professionalità.

Studiate i vostri errori e se siete in dubbio chiedete il perché di una correzione; di nuovo, la vostra inclinazione al miglioramento sarà ben gradita all’editor e vi distinguerà sicuramente dagli altri.

Per approfondire

In questo articolo ho cercato di dare alcuni consigli per la stesura di articoli tecnici. Un articolo è efficace quando, oltre a informare, convince il lettore della sua validità.
I suggerimenti esposti non costituiscono certo la “guida completa” al technical writing, e vanno integrati con letture specifiche (o più generali) sulla scrittura.

Per iniziare non posso che citare Il nuovo manuale di stile di Roberto Lesina (Zanichelli), che non dovrebbe mai mancare sulla scrivania di uno scrittore (tecnico e non). 
Se scrivete in italiano vi può essere utile ripassare velocemente le regole grammaticali e ortografiche con Italiano. Corso di sopravvivenza di Massimo Birattari (Ponte alle Grazie). 
Qualsiasi sia il vostro grado di preparazione nella scrittura, consiglio vivamente Italiano: Lo Stile, sempre di Massimo Birattari, un eccellente manuale per migliorare l’efficacia della scrittura. Sia io che i miei colleghi ne abbiamo tratto giovamento e abbiamo migliorato lo stile, sia italiano che inglese.
Per quanto riguarda la letteratura specifica per il technical writing, Fondamenti di comunicazione tecnico-scientifica di Emilio Matricciani (Apogeo) contiene tutto quello che bisogna sapere sulla scrittura tecnica, è ben scritto e soprattutto completo. Consigliato a chi vuole intraprendere seriamente la carriera di technical writer.

Alberto Falossi è formatore e consulente informatico per la Code Architects Srl. 
È autore di numerosi articoli tecnici per riviste e siti web e technical reviewer per articoli e libri tecnici, sia italiani che inglesi. 
È il direttore tecnico di una rivista informatica italiana e cura alcune sezioni di un noto portale internazionale di programmazione (www.vb2themax.com). 
Può essere contattato tramite il sito www.albertofalossi.com, da dove si accede anche al suo blog.

| appunti | al lavoro! | scrivere per il web | link | glossario | blog | riscritture | quaderni | litbits |caro visitatore | istruzioni per l'uso | sitemap | mappa tematica | scrivi | cerca | home |

Pagina aggiornata il 13.11.03