Alessandro Del Sole's Blog

{ A programming space about Microsoft® .NET® }
posts - 1907, comments - 2047, trackbacks - 352

My Links

News

Your host

This is me! Questo spazio è dedicato a Microsoft® .NET®, di cui sono molto appassionato :-)

Cookie e Privacy

Disabilita cookie ShinyStat

Microsoft MVP

My MVP Profile

Microsoft Certified Professional

Microsoft Specialist

Xamarin Certified Mobile Developer

Il mio libro su VB 2015!

Pre-ordina il mio libro su VB 2015 Pre-ordina il mio libro "Visual Basic 2015 Unleashed". Clicca sulla copertina per informazioni!

Il mio libro su WPF 4.5.1!

Clicca sulla copertina per informazioni! E' uscito il mio libro "Programmare con WPF 4.5.1". Clicca sulla copertina per informazioni!

These postings are provided 'AS IS' for entertainment purposes only with absolutely no warranty expressed or implied and confer no rights.
If you're not an Italian user, please visit my English blog

Le vostre visite

I'm a VB!

Guarda la mia intervista a Seattle

Follow me on Twitter!

Altri spazi

GitHub
I miei progetti open-source su GitHub

Article Categories

Archives

Post Categories

Image Galleries

Privacy Policy

Tips & Tricks per la scrittura di contenuti tecnici

Ognuno di noi, soprattutto in ambito tecnico, impara dagli altri. Per aggiornarci, informarci, ma anche risolvere problemi tecnici, leggiamo articoli, libri, contenuti vari. Personalmente scrivo da parecchi anni. Mi è sempre piaciuto poter dare il mio contributo alla comunità di sviluppatori.

Ho cominciato a scrivere articoli per Visual Basic Tips & Tricks nel 2000, ho avuto il privilegio, la fortuna, la fatica anche di scrivere parecchi libri e articoli in inglese, in molti casi anche per editori prestigiosi come MSDN Magazine.
Ovviamente gli anni portano esperienza e sicuramente questa, oggi, mi agevola molto soprattutto con l’editoria americana, piuttosto diversa dalla nostra. E così, poiché io stesso come te mi documento e mi aggiorno da contenuti tecnici, ho pensato di raccogliere in questo post alcune lezioni che ho imparato in questa attività e che spero possano essere utili soprattutto a chi scrive con meno frequenza e ha meno esperienza.

Perchè voglio scrivere?
Sembra una domanda banale ma è alla base dell’attività ed è strettamente correlata al paragrafo successivo. Ci sono essenzialmente quattro motivi che ci portano a scrivere contenuti tecnici, che spesso si intersecano e uniscono tra loro: passione per la condivisione della conoscenza, rafforzare la propria reputazione, per questioni economiche o perché ci viene chiesto da terzi, come un editore. Sono tutte giuste e lecite, non sto qui a discuterle. L’ultima ti risolve (quasi sempre) il problema della scelta  dell’argomento di cui parlare, che si tratti di un articolo o di un libro. Pensa dentro di te cosa ti spinge a farlo. Il motivo lo scoprirai tra breve.

Scelta degli argomenti da trattare
Questo è un punto cruciale. Da qui dipende prevalentemente l’impegno che ti richiederà scrivere e buona parte dell’interesse che la tua produzione riscuoterà. Se lo fai perché ti viene chiesto da un editore o  comunque da terzi, parte del problema è risolto nel senso che ti verrà quasi sicuramente proposto anche  l’argomento su cui, magari, sei già preparato. Se scrivi prevalentemente perché ti piace o perché hai  passione per la condivisione di ciò che sai o di ciò che hai sperimentato, provato, risolto, sei  completamente libero di scegliere il tuo argomento, indipendentemente dall’audience che ti aspetti (ma  non trascurare comunque il paragrafo successivo). Se lo fai per gli altri motivi, la scelta diventa un po’ più complicata e va fatta con criterio. Può essere una buona idea quella di discutere qualcosa in voga in un  certo periodo, un c.d. trending topic. Oppure puoi prendere spunto da discussioni nei forum tecnici, che  sono spesso una grande fonte di problemi reali che puoi descrivere come risolvere con un buon articolo.  Se i motivi che ti inducono a scrivere sono molteplici e si incrociano tra loro, una buona idea è discutere un problema che può verificarsi in un trending topic e come risolverlo, oppure descrivere specifiche funzionalità. Non ti consiglio di parlare di cose troppo in anteprima o che, comunque, non è ancora  possibile provare. A noi tecnici piace giocare, sperimentare in pratica, il futuro dev’essere anche  “toccabile” e, qui, non siamo negli USA.

Ciò che scrivi è di tutti
Un grosso, grosso errore è quello di pensare che la tua audience possa essere ristretta, soprattutto se  non scrivi con una certa frequenza e soprattutto se non hai mai scritto per editori di un certo livello, con  un certo blasone e con una certa visibilità. Quando scrivi un articolo che viene pubblicato su Internet o un  libro venduto nelle librerie fisiche o online, dalla sua pubblicazione non hai più alcun controllo su chi e quanti  potranno leggerlo. Questa parentesi è importante: quando scrivi, pensa sempre che ci sarà qualcuno che leggerà ciò che hai prodotto. Non pensare mai che lo possano leggere in pochi o che lo  leggeranno solo quelli che non sono già esperti di un certo argomento. Tutti, anche gli esperti, hanno da  imparare da ogni buon contenuto. Perciò, anche se lo fai solo per hobby o per passione, scrivi in modo  che gli altri possano capire e imparare. Scrivi pensando a come tu vorresti capire le cose che scrivono o  descrivono gli altri. Meglio essere semplici, comprensibili e tecnicamente accurati piuttosto che altisonanti ma con poca sostanza.

Fidati di te stesso, ma non troppo
Se lavori su un articolo o su un libro che riguarda un certo argomento, è evidente che tu ti senta  preparato per discuterlo. Purtroppo, però, nessuno di noi è infallibile. Il rischio di scrivere cose inesatte è  sempre dietro l’angolo e da questo può dipendere la tua reputazione di “scrittore”. Quando scrivi, perciò,  affidati a uno o più revisori tecnici preparati sugli argomenti che tratti. Chiaro che questo non può avvenire su un blog personale del quale, in quanto tale, ne sei responsabile in prima persona. Nel caso tu scriva per degli editori,  la revisione tecnica è un passaggio imprescindibile della pipeline, quindi questo ti eviterà di preoccuparti  di cercare un revisore: ti verrà assegnato comunque. Se però scrivi per tuo conto o se scrivi per entità  (es. siti web) che non prevedono una revisione tecnica, non trascurarla e chiedi a qualcuno che conosci.  Considera pure che, in molti casi, l’argomento che tratti si intreccia con altri che conosci meno. Meglio  metterci qualche ora in più ma essere sicuri che i contenuti siano esatti. D’altronde, anche tu ti  aspetteresti che i contenuti che leggi siano tecnicamente accurati. Lo stesso faranno gli altri con te.

Le misure contano
Contenuti troppo brevi rischiano di essere incompleti e frettolosi, mentre troppo lunghi rischiano di essere dispersivi e noiosi. Solo l’esperienza di potrà aiutare a trovare il giusto equilibrio in ciò che scrivi, il consiglio che posso darti è questo: cerca di andare alla sostanza delle cose senza tanti fronzoli,  assicurandoti, però, di dare quel minimo di base necessaria per riuscire a capirla. Altrimenti, se devi scegliere, scegli di scrivere di più. Se vuoi parlare di Code First in Entity Framework, insomma, assicurati di descrivere almeno cosa sia quest’ultimo. Ma non è necessario descrivere tutti e 4 i template che la finestra New Entity Data Model ti mette a disposizione. Questo è il senso.

Scrivere bene ti conviene (semicit.)
Intendiamoci, non bisogna essere professori di lingua per scrivere contenuti tecnici. Ci mancherebbe altro. Ma non c’è dubbio che scrivere il più possibile correttamente nella lingua richiesta ha il suo peso per vari  motivi: come scrivi è visibile e già questo darà un’idea di te, soprattutto quando scrivi nella tua lingua madre; scrivere in modo lineare e corretto aiuta gli altri a capire meglio il tuo contenuto (pensa sempre a cosa tu ti aspetteresti). Infine, soprattutto se scrivi per un editore, aiuterai la figura del revisore linguistico a essere più veloce ed efficace, a dover fare meno correzioni e, conseguentemente, a rispettare il cosiddetto time-to-market. Un discorso a parte, sebbene collegato, è quello dello scrivere in un’altra lingua. Sicuramente l’editore estero ha una certa indulgenza, comprendendo che quella non è la tua lingua madre. Ma se ti renderai conto che ti si aprono delle opportunità e che la collaborazione va avanti, soprattutto se ti rendi conto che hai delle lacune  grammaticali e di vocaboli in quella lingua, non trascurare la possibilità di un corso. Questo ti renderà non solo più sicuro di te, ma porterà una migliore considerazione nei confronti tuoi e dei tuoi contenuti. Prova a pensare a un revisore tecnico o a un revisore linguistico che devono capire delle frasi scritte in modo approssimativo: a una soluzione ci si arriva sempre, ma richiede il triplo del tempo con inevitabili ripercussioni sul processo. E sulle tue opportunità future. Io scrivo moltissimo in inglese, ormai forse più che in italiano. La mia fortuna è stata quella di essermi appassionato all’inglese ai tempi delle scuole medie. Ovviamente, però, scrivere in inglese tecnico non è la stessa cosa. Oggi ho il piacere di ricevere tanti complimenti per il mio inglese dai più importanti editori con cui ho collaborato (SAMS, Syncfusion, MSDN Magazine) ma chiaramente c’è del lavoro dietro. L’esercizio è stato fondamentale, così come il leggere contenuti tecnici quasi esclusivamente in inglese. Facendo questo, negli anni passati ho imparato tantissimo su come scrivere in un buon inglese, tutte cose che oggi mi ritrovo e che mi permettono di essere più veloce. Inoltre, e qui torna l’importanza della figura dei revisori, ho sempre cercato di fare mie le espressioni utilizzate dal revisore tecnico o linguistico, sapendo che quello era il modo in cui in inglese si comunicano determinate cose. Scrivere in un buon inglese oggi per me è fondamentale, perché permette di essere più veloce a me sicuramente ma conseguentemente anche a chi pubblicherà i miei contenuti.
Ultima nota: se decidi di aprire un blog in inglese, assicurati di scrivere in un inglese mediamente corretto: l'audience, infatti, non sarà indulgente come un editore.

Conclusione: Impara dagli altri e fai tesoro dell’esperienza
Concludo qui e poi non vi annoio oltre. Leggi gli articoli di chi ha una reputazione tecnica stabile, impara a capire come vengono strutturati e descritti gli argomenti, poi lanciati e vedrai che, articolo dopo articolo, non solo migliorerai tu ma anche i tuoi contenuti. Di conseguenza, migliorerà la tua reputation con le conseguenze del caso.

Alessandro

Print | posted on venerdì 20 maggio 2016 10:41 | Filed Under [ Community and friends ]

Powered by:
Powered By Subtext Powered By ASP.NET