I professionisti dell’IT, che si tratti di architetti, project manager, commerciali o sviluppatori, si trovano spesso a dover scrivere documenti di varia tipologia: analisi dei requisiti, presentazioni di progetti, resoconti tecnici e così via. Ci sono delle strategie che possono migliorare la qualità e la leggibilità di tali documenti? Vediamo insieme alcuni consigli semplici per scrivere documenti migliori.

In questo articolo vorrei condividere con i lettori alcune delle pratiche che ho appreso nel corso degli anni in merito alla scrittura di articoli o genericamente di documenti (documentazione di progetto, presentazioni di vario tipo, resoconti, post su blog, etc.). Lo scopo di questo contributo alla rivista è quello di rendere pubbliche alcune pratiche e tecniche di lavoro derivanti quasi esclusivamente dal lavoro sul campo e dall’esperienza personale (e sottolineo personale); non c’è in alcun modo la pretesa di voler affrontare il tema da un punto di vista teorico o formale.

Spero che quanto riportato possa essere di una qualche utilità per i lettori che magari troveranno giovamento nell’applicare qualcuno dei consigli qui presentati.

Organizzazione della struttura dell’articolo

Spesso, anche lo scrittore più navigato prova difficoltà nell’organizzare i concetti che si affollano in testa, rimanendo bloccato di fronte all’indecisione sul come organizzarli e sul come definire un filo logico.

Il blocco creativo, detto “sindrome da foglio bianco” può protrarsi per parecchio tempo nel tentativo di trovare la strada giusta, momento in cui in genere tutto appare chiaro e il filo logico si paventa chiaro davanti ai nostri occhi. Normalmente, all’indecisione sul percorso da intraprendere, si unisce lo scoramento per la montagna che ci apprestiamo a scalare: già fossimo a metà dell’opera, il lavoro ci sembrerebbe meno impegnativo e per assurdo ne trarremmo stimolo a procedere in modo ancora più rapido: il detto “chi ben comincia è già a metà dell’opera” è quantomai vero e in questo caso si può estendere con “chi è a metà dell’opera sente di aver già intrapreso la strada finale”.

Documenti come progetti

La difficoltà spesso è quindi quella di trovare un modo per velocizzare il tempo di startup di progetto: scrivere un articolo o un documento è una attività che ha un inizio, una fine e un obiettivo da raggiungere, quindi per definizione è assimilabile a un progetto, a uno di quelli con cui ci confrontiamo quotidianamente.Occorre superare in maniera rapida i primi passi di questo cammino, in modo che l’entusiasmo per la progressione ci dia una spinta a procedere al meglio. In tal senso, il conta-caratteri è un ottimo alleato se visto con spirito ottimista. Una piccola nota tecnica: quando usiamo il conta-caratteri del nostro programma di scrittura, ricordiamoci che contano le battute, ossia i “caratteri spazi inclusi”: le parole o i caratteri senza contare gli spazi sono “unità di misura” usate in altri contesti.

Scaletta

Uno strategemma piuttosto efficace quando il blocco prende il totale controllo è quello di partire dalla stesura dello scheletro dell’articolo scrivendo per prima cosa l’elenco dei paragrafi con anche una ipotesi di lunghezza che si vorrà dare a ogni sezione (in base all’importanza presunta della singola sezione. Per dar vita a questa suddivisione si può partire da uno schema tipico col quale è possibile dare una prima impostazione standard; per fare un esempio lo schema potrebbe essere fatto in questo modo (tra parentesi il numero di battute di ogni paragrafo o sezione):

• intro (2500)
• argomento-1 (5000)
• argomento-2 (5000)
• argomento-3 (2000)
• considerazioni (2500)
• conclusioni (1500)
• riferimenti e bliografia (1000)

Con uno schema di questo tipo abbiamo compreso che possiamo raccontare tre macro-temi (argomento-1, argomento-2, argomento-3) di cui due importanti e uno un po’ meno e che il tutto è poi confezionabile in un articolo da poco più di 19k caratteri.

Ovviamente la parte difficile è trovare i tre argomenti, ma normalmente se l’argomento è noto, l’autore ci ha lavorato a lungo e ha quindi molta esperienza diretta, la difficoltà sarà esattamente quella di scrivere e non di cercare.

L’utilizzo di uno scheletro preimpostato è utile perche’ facilita il lavoro di stesura grazie alla possibilità di lavorare un po’ per volta alle varie parti dell’articolo senza richiedere una full immersion di tante ore consecutive. In questo modo poi, non c’è un “inizio obbligato” dei lavori, perche’ a parte qualche sezione, si può davvero cominciare da uno qualunque degli argomenti, superando il blocco da “foglio bianco” e vedendo che intanto il nostro documento “si popola”:

Ricerca vs. “Copia e incolla”

Chiaramente, nella scrittura di un articolo tecnico o di un documento di progetto, non tutto il testo sarà esclusivamente originale. Ci sarà anche la possibilità in cui si debba sintetizzare concetti trovati altrove, o si debba includere del testo tradotto. In tale situazione, un oculato “copia e incolla” è ammissibile, ma solo se se accompagnato da una adeguata operazione di sintesi critica e da una doverosa citazione delle fonti.

Se ad esempio, ricorriamo anche a questa pratica, i brani di testo che si trovano altrove e che poi andranno rielaborati/tradotti/criticati possono essere direttamente inseriti nella giusta collocazione facendo riferimento allo schema di scaletta riportata poco sopra.

Citare le fonti è importante e doveroso e, se si ricorre a citazioni abbastanza estese, occorre valutare se non sia il caso di richiedere l’autorizzazione all’autore o all’editore. In ogni caso, un testo che citi le sue fonti potrà fornire interessanti spunti al lettore e spingerlo ad approfondire. E se anche magari l’articolo non sarà troppo originale, un buon lavoro di sintesi e di organizzazione dei contenuti vale davvero molto e può rappresentare un punto di riferimento per molti lettori.

Anche se siete ottimi traduttori (il che implica una ottima conoscenza della lingua da tradurre, ma una ancor migliore conoscenza dell’italiano), un testo tradotto brutalmente senza rielaborazione appare al lettore accorto per quello che è: un testo “copiato” senza sintesi critica. E non dimenticate inoltre che più si lavora di patchwork durante la prima stesura, maggiore dovrà essere l’attenzione dedicata alla fase di armonizzazione, revisione e limatura, per non pubblicare poi un testo stile Frankenstein, risultante dall’assemblaggio di pezzi molto diversi fra loro.

Uniformità stilistica

La ricerca di una uniformità stilistica nel testo che si sta confezionando non deve fermarsi solo all’aspetto di organizzazione dei contenuti o di armonizzazione linguistica, ma anche nel modo in cui il testo viene presentato graficamente: testi analoghi scritti con caratteri diversi e font lasciate al caso, sottolineature (da evitare, si usano solo per i link), paragrafi con rientri ballerini, titoli senza un precisa organizzazione gerarchica non fanno altro che confondere il lettore e suggerirgli l’idea che quel testo è un patchwork raffazzonato. Una cura verso l’uniformazione redazionale e grafica è fondamentale per una migliore comprensione dei concetti contenuti nel testo: in questo caso, davvero, “la forma è anche sostanza”.

Lunghezza e statistiche

Si è fatto cenno alla lunghezza di un articolo nell’esempio dello schema degli argomenti, ma quanto deve essere lungo un articolo? Una notizia su un blog? Una pagina di Wiki? Ovviamente non c’è una regola, si deve sempre contesutalizzare in funzione di quello che si deve dire e del dove lo si deve dire: un blog, una rivista, un documento tecnico, etc.

In MokaByte ci siamo dati una serie di regole basate sull’esperienza, mediando fra la capacità di attenzione del lettore e la disponiblità dell’autore nello scrivere (non si deve mai approfittare di nessuno dei due). Nel nostro caso un articolo non dovrebbe essre meno lungo di 12k di battute e non dovrebbe superare i 20k di battute. Tale limite si può superare, in casi particolari in cui siano molte cose da dire che non è possibile rimandare a un altro appuntamento (guardate, ad esempio, il lungo articolo sulla storia di Java pubblicato in questo numero).

Livello di attenzione

Si consideri sempre che il limite di lunghezza va empiricamente calcolato sul livello di attenzione che un lettore pone nella lettura di un testo: mi immagino che oltre tale limite si debba rimandare la lettura in più momenti e quindi la concentrazione in genere diminuisce. Parallelamente anche dal punto di vista dell’autore, scrivere un articolo che sia più lungo di tale limite diventa molto faticoso sia dal punto di vista della prima stesura che, sopratutto, in fase di revisione e correzione (mentre rileggo un mio articolo, se è troppo lungo, rischio di perdere un po’ il filo del ragionamento).

Ovviamente queste indicazioni sono valide per un testo di media grandezza, esempio un articolo o un documento di ampio respiro. Spesso le indicazioni sono fornite dalla redazione per la quale si sta lavorando, specialmente se si deve andare su carta; questo limite generalmente decade se si scrive per un blog o un per un giornale elettronico dove non ci sono costi di produzione (carta), ma solo di processo. In ogni caso, però, come ben saprete, i testi che devono essere fruiti attraverso il web devono privilegiare la sintesi e la concisione.

Curva degli approfondimenti

Spesso capita di dover affrontare un argomento particolarmente vasto ma lo spazio a disposizione, così come la concentrazione del lettore o più genericamente di chi ci sta ad ascoltare, non consentono di affrontare ogni punto con il sufficiente dettaglio che si reputa necessario. Spesso questa è una convinzione errata, dato che, se si pensa di scomporre il tema principale, raramente un determinato argomento è composto di sottoparti aventi tutti lo stesso peso o la stessa importanza.

Contesto

Spesso il valore di ogni capitolo dipende dal contesto o dalla tipologia dei lettori: se immaginiamo di dover parlare di programmazione distribuita, il taglio che si dovrà dare è molto diverso se scrivo per architetti o per programmatori o per capi progetto, così come sarà diverso il peso di ogni capitolo. Il problema è però questo: se devo parlare a una platea, ho probabilmente già chiaro di chi si tratta e posso comunque ricevere feedback immediati sul “successo” della mia comunicazione. Se pensate a una presentazione, o a una lezione in aula, ad esempio, si capisce immediatamente (dall’entusiasmo, dalle facce perplesse, dalle eventuali domande) se ho realizzato una comunicazione adeguata al mio “ascoltatore ideale”.

Più difficile è calibrare il testo per il contesto se devo scrivere per un pubblico di lettori che non vedo in faccia, di cui non percepisco le reazioni, che non so esattamente definire in termini di preparazione, interessi, capacità, attenzione etc. I grandi sforzi effettuati dai grandi colossi editoriali per il “profiling” dei propri lettori tenta, almeno in parte, di superare questo problema.

Peculiarità

Con tutta probabilità, relativamente al tema che vi siete prefissati di raccontare, è presumibile che in rete o in libreria ci siano scritti molto più completi e vasti del vostro. E allora, perche’ un lettore dovrebbe decidere di concedervi il suo tempo leggendo il vostro manufatto? Probabilmente è perche’ confida o spera di trovare in questo documento qualcosa di diverso: potrebbe essere un commento oculato o una particolare interpretazione, che parta dal dare per scontato gli aspetti teorici; oppure il vostro testo potrebbe fornire un approfondimento particolare solo su alcuni particolari aspetti interessanti di un topic molto vasto. Insomma, occorre che il vostro scritto abbia una qualsivoglia peculiarità, sia anche solo una perfetta sintesi ordinata di materiale preesistente.

Questo approccio è esattamente quello che personalmente ho sempre cercato di adottare nella scrittura dei miei articoli, ovvero offrire la mia personale esperienza di consulente Java maturata dal lavoro diretto su progetti o dai clienti, andando a focalizzare l’attenzione solo su quegli aspetti per i quali sapevo esserci un interesse o comunque una necessità di approfondimento. Stesso approccio fu quello del libro realizzato oramai quasi dieci anni fa da autori di MokaByte, “Manuale Pratico di Java” (Hops/Tecniche Nuove), che sebbene scritto da persone completamente sconosciute al mondo editoriale classico, ha avuto un enorme successo proprio perche’ evidentemente aveva saputo trovare la giusta miscela di argomenti e il giusto modo di proporli.

Come funziona la curva degli approfondimenti

Per semplificare questo passaggio molto delicato e importante, da cui dipende spesso tutto l’equilibrio dell’articolo e l’interesse finale, nel corso degli anni ho affinato una tecnica tutta personale alla quale ricorro quando devo affrontare un argomento particolarmente ampio. La tecnica che seguo l’ho denominata curva degli approfondimenti: si parte dallo svolgere una trattazione ad alto livello di tutto il tema in esame, senza scendere nel dettaglio di alcun argomento, ma facendo una panoramica su tutti i vari punti. Dopo questa trattazione di superfice, scelgo quei due o tre aspetti su cui svolgere un approfondimento: a volte in un articolo c’è posto per un solo “deep”.

In questo modo il lettore avrà comunque modo di poter vedere la cosiddetta “big picture” ovvero la panoramica d’insieme, e di riuscire comunque ad avere i giusti approfondimenti sugli aspetti salienti (perlomeno su quelli ritenuti tali dall’autore). La vera sfida in questo caso è individuare i topic su cui fare gli approfondimenti, ma se con un po’ di esperienza è possibile trovare il modo per selezionarli, la curva degli approfondimenti può aggiungere quel tocco di pragmatismo e di efficacia indispensabili per realizzare una comunicazione efficace.

Figura 1 – La curva degli approfondimenti: grazie a questo grafico si possono creare delle astrazioni sul livello di astrazione medio e sui vari approfondimenti relativi ai temi “caldi” che vogliamo trattare in maggior dettaglio. Ovviamente è un diagramma che non si poggia su alcuna base numerica o scientifica, ma è più un modo per fissare le idee e velocizzare la stesura.

Partizionamento: in che modo suddividere un argomento

Proseguendo sul tema della complessità e della lunghezza, se decidessimo di spezzare un argomento in sottoparti, potrebbere sorgere il dubbio su quale sia il modo corretto di spezzare il documento.

Una possibile soluzione potrebbe essere quella di guidare il lettore in un percorso che introduca prima al contesto nel quale il problema che stiamo affrontando si inserisce: in questa parte potremmo iniziare col presentare alcuni casi tipici che si verificano nell’ambito lavorativo, in azienda o altrove. Tale contestualizzazione potrebbe dar maggior rilievo al problema e quindi valorizzare una eventuale soluzione che presenteremo solo nella seconda puntata. Questa seconda parte potrebbe essere organizzata secondo il classico schema della curva degli approfondimenti. Se in questo caso le cose da dire sono molte, si potrebbe pensare di spezzare questa seconda parte in più pezzi in modo da rimanere chiari senza dover per forza dire tantissime cose nello spazio di un solo articolo.

Nella terza parte infine si potrebbe pensare di affrontare il tema delle implicazioni derivanti dalle varie soluzioni presentate in precedenza.

La lezione della retorica

Questa impostazione è tipica della cultura occidentale, ci viene insegnata fin da piccoli risale alle tecniche della retorica antica. Si tratta, tutto sommato, della classica questione della inventio (trovare gli argomenti) e della dispositio, (disporre gli argomenti secondo uno schema preciso) presente negli insegnamenti di Quintiliano (I sec d.C.).

La disposizione degli argomenti, secondo Quintiliano [1], era sostanzialmente la seguente:

• un esordio con il tentativo di accattivarsi l’uditorio tramite battute divertenti o esempi commoventi;
• una narrazione in cui si esponevano all’uditorio i fatti, con lo scopo di spiegare la questione, l’intento di insegnare qualcosa;
• una argomentazione, cioè la dimostrazione delle prove a sostegno della propria tesi e a confutazione degli argomenti avversari;
• un epilogo, la conclusione del discorso, la “perorazione”, in cui si cerca di far leva anche e soprattutto sugli aspetti “emozionali” dell’uditorio.

Tutti abbiamo esperienza di questa “metodologia” classica di costruzione del discorso: le arringhe degli avvocati nei telefilm a sfondo legale sono costruite così; ma è anche il modo in cui doveva essere svolto il compito in classe per realizzare un buon tema d’italiano.

Questo schema retorico è alla base del nostro modo di ragionare e di presentare i concetti: del resto, lasciare il piatto forte per ultimo è una tecnica che dovrebbe tenere alta l’attenzione del lettore in modo da costringerlo a rimanere attento fino in fondo. Se ci pensate, funzionano così anche le fiabe per bambini, o gran parte delle produzioni cinematografiche.

La scrittura professionale moderna

Nonostante la lezione degli antichi sia da rispettare e sia certo interessante da studiare, nell’età contemporanea i nuovi mezzi di comunicazione di massa (prima i giornali, poi la radio e la TV, infine il web) hanno favorito la nascita di nuovi linguaggi e anche di una metodologia di disposizione dei contenuti strutturata in modo diverso rispetto alle idee di Quintiliano. La lingua che viene usata per la scrittura in rete, ma anche per le presentazioni o per un documento di progetto, deve essere necessariamente più veloce, più concisa, più concentrata, senza però diventare sciatta. Efficienza ed efficacia della comunicazione devono essere al centro degli sforzi di chi intenda “raccontare” qualcosa: che si tratti del nuovo framework di sviluppo, di un progetto software per un ente bancario, del resoconto di una riunione tecnica, o delle informazioni contenute sulla pagina di un Wiki.

Di tali temi, in ambito strettamente IT, si è occupato tra i primi Jakob Nielsen [2] un ingegnere della Sun MicroSytem, che, preoccupandosi dei concetti di usabilità delle pagine web, comincia fin dalla fine degli anni Novanta a sottolineare per la scrittura dei contenuti testuali anche l’importanza di una lingua semplice, chiara, concisa, e di una precisa strutturazione dei contenuti che “ribalta” i concetti della retorica classica a cui tutti siamo stati abituati.

In particolare, egli mette a punto dei concetti semplici ma efficaci, che devono guidare nella scrittura dei contenuti testuali[3], nell’ottica di una migliore fruizione dei testi da parte dei lettori:

• piramide invertita: occorre rovesciare il modo tradizionale di esporre i concetti; per prima cosa si espone brevemente la “conclusione”, poi si penserà a sviluppare tutta la discussione
• microcontenuti: ci sono alcune parti del discorso che rappresentano dei punti molto importanti del discorso (titoli, link, parole chiave); queste parti vanno opportunamente messe in evidenza (caratterizzazione con grassetto o colore, collegamento ipertestuale etc.); un microcontenuto non supera, in genere le 40-50 battute.
• abstract: un riassunto breve del contenuto che segue, a inizio del discorso, facilita il lettore nell’entrare nel contesto e nel capire se ciò che segue può in qualche modo interessarlo oppure no.

Una posizione del genere, specie nel panorama americano, è ampiamente condivisa. Ad esempio, una blogger che si occupa di queste tematiche [4] suggerisce di andare subito al punto, o perlomeno di provarci. Alcune tecniche che si possono usare sono le seguenti:

• partire dal presentare molto brevementre il “contesto” all’interno del quale si colloca il problema che andremo a presentare (e si spera a risolvere).
• aumentare l’attenzione: tecnica molto comune, usata anche dai comici prima della battuta finale in cui la suspence o un paragone assurdo può amplificare l’effetto dirompente della battuta finale.
• ripetere durante l’esposizione i concetti-chiave.
• facilitare i processi di decisione.
• violare le regole, se necessario in casi particolari.

Questi principi, e l’invito a trattare subito il punto cruciale dopo aver brevemente presentato un abstract del discorso,valgono per la scrittura in rete e ancor più per le presentazioni. Di questo ci accorgiamo sempre più spesso quando certi concetti non vengono osservati, per esempio quando un presentatore comincia il discorso spiegandoci per infiniti minuti tutt la storia dell’azienda e magari i diversi organigrammi che si sono succeduti (“Nasciamo nel 1986, come joint venture”, “Nel 1991, l’ing. X assume il ruolo di presdidente e il dott.Y quello di responsabile marketing”, “La nostra mission è basata su un perfetto equilibrio di tradizione e innovazione”) scatenando negli astanti un motivato “e chi se ne frega”…

Cicli lavorativi

Ci sono momenti della giornata o della settimana in cui si lavora meglio; in queste momenti il testo fluisce via libero senza problemi, i periodi sono puliti e ben organizzati, è facile impostare un filo logico che abbia senso e il documento si scrive quasi da solo. Altre volte capita che per scrivere anche solo un paragrafo diventa una impresa titanica. Personalmente quando mi accorgo di non riuscire a fare a meno di periodi annidati, troppe parentesi, o infiniti blocchi di testo senza adeguati titoli e sottotitoli, desumo di essere in un cattivo momento e chiudo il file.

È quindi preferibile organizzarsi il tempo in modo da dedicare alla scrittura quei momenti in cui si è maggiormente rilassati o in cui la testa è libera da troppi pensieri. Ognuno ha la sua strategia: una buona musica in cuffia aiusta alcuni a isolarsi o a concentrarsi, un po’ di attività fisica predispone a un migliore ordinamento dei concetti, una doccia calda o una buona bevanda possono aiutare a stimolare la condizione psicofisica migliore.

Conclusione

In definitiva, scrivere un testo “tecnico” ha le sue difficoltà specie quando occorre farlo in condizioni di stress e con stretti tempi di consegna. Al di là delle tecniche e degli insegnamenti ricevuti, quel che conta di più è uno sforzo cosciente per mantenere alto il livello di qualità della comunicazione. L’ordine, la chiarezza, la strutturazione dei contenuti, la loro presentazione grafica devono essere vissuti come strumenti per ottenere una comunicazione efficace, capace di trasmettere alcuni semplici concetti in modo inequivocabile. Non si possono mai dire tutti i concetti: ma si può sempre dire almeno qualcuno di essi, in modo diretto, chiaro ed efficace.

Riferimenti

[1] Marcus Fabius Quintilianus, Institutio oratoria

http://rhetoric.eserver.org/quintilian/1/index.html

[2] La biografia di Jakob Nielsen

http://www.useit.com/jakob/

[3] Jakob Nielsen – Hoa Loranger, “Web Usability 2.0. L’usabilità che conta”, Apogeo Editore, 2006

[4] Olivia Mitchell, “Presentation structure: Why it’s smarter to put your conclusion in your opening”

http://www.speakingaboutpresenting.com/content/presentation-structure-conclusion/