Come scrivere una documentazione tecnica efficace

Se sviluppi temi e plugin, la documentazione tecnica dovrebbe essere un tassello fondamentale per supportare le persone che usano il tuo prodotto.
Eppure spesso la stesura dei documenti tecnici viene bistrattata o relegata a oscure pagine scritte in “tecnichese”.
In questa presentazione vedremo alcune buone pratiche per scrivere una documentazione tecnica efficace, anche quando l’argomento da trattare è ostico.
Vedremo come produrre testi chiari, che sappiano parlare al tuo pubblico di riferimento senza fargli venire il mal di testa e, soprattutto, che offrano tutte le risposte necessarie per usare al meglio il tuo tema o plugin.

Transcript

1. Scrivere una documentazione tecnica efficace: Lo stai facendo bene? Alice Orrù WordCamp Italia - 17 ottobre 2020
2. Ciao! Mi chiamo Alice Orrù Sono una copywriter con il pallino per la documentazione tecnica e il linguaggio inclusivo Mi trovi su: aliceorru.me 2
3. Documentazione tecnica per il tuo tema o plugin ▶ Perché scriverla ▶ Come scriverla ‣ Scegliere le parole ‣ Organizzare i contenuti ‣ Rendere i contenuti accessibili ▶ Risorse utili 3
4. 1. Perché scrivere una documentazione tecnica Partiamo dalla base 4
5. TRE MOTIVI Supporto Una documentazione tecnica efficace guida le persone che iniziano a usare il tuo prodotto e le rende autonome. Risparmio Se le persone si sentono accompagnate, ricorreranno meno al supporto e alleggeriranno il tuo carico di lavoro. Branding Una documentazione tecnica ben scritta rafforza la tua marca e la reputazione del tuo prodotto. 5
6. 2. Come scrivere la tua documentazione tecnica I consigli di una copywriter 6
7. Scegliere le parole 7
8. 8 Ascolto Consistenza Chiarezza Risposte Il percorso delle parole
9. Come parlano le persone che usano il tuo prodotto? Quali termini usano per descrivere i problemi che incontrano? 9 Ascolta il tuo pubblico:
10. La documentazione tecnica serve a risolvere dubbi, non a far venire altre domande. 10 Scegli parole chiare, semplici, accessibili:
11. 11 ▶ Scrivi frasi brevi ▶ Usa la forma attiva ▶ Evita il gergo o parole troppo lunghe (es. gli avverbi in -mente) ▶ Riassumi i punti principali in cima alla pagina ▶ Titoli chiari, descrittivi Scegli parole chiare, semplici, accessibili:
12. Usa la stessa parola per descrivere un concetto che ripeti spesso. Es. Bacheca WordPress o Cruscotto WordPress? 12 Mantieni la consistenza del linguaggio:
13. 13 1. Quali problemi risolve il prodotto? 2. Quali sono le sue caratteristiche principali? 3. Come si installa? 4. Dove trovo esempi di codice o tutorial? 5. Come contattare una persona in carne e ossa che offra supporto? 6. Posso contribuire? 7. Dove trovo il changelog? Le domande a cui risponde la tua documentazione tecnica
14. Organizzare i contenuti 14
15. Da dove iniziare? 15 Pensa alla documentazione tecnica come a un manuale di istruzioni per montare un mobile. Parti sempre dai concetti di base. D’altronde ogni buon manuale di istruzioni ti mostra per prima cosa gli attrezzi da usare, no?
16. Chi usa il tuo prodotto potrebbe perdersi in qualsiasi punto del procedimento. Non aver paura di dare istruzioni (solo in apparenza) banali. 16 Non dare nulla per scontato:
17. 17 La struttura del testo: come leggiamo le pagine web Fonte: Chandrananth, Janan & Fraval, Andrew & YM, Chong & M, Chandrananth & Tran, Phong. (2017). “A Guide to Writing eHealth Websites with Orthopaedics as an Example - Readability, Reliability, Usability” Già alla fine degli anni ‘90, uno studio * di Nielsen e Morkes scopre che: - il 79% delle persone scansiona sempre ogni nuova pagina che incontra - solo il 16% legge parola per parola La forma più comune di scansione è quella a forma di F. (* How Users Read on the Web)
18. 18 La struttura del testo ▶ L’informazione importante va all’inizio della pagina ▶ Separa il testo in blocchi ▶ Usa i tag header per stabilire le gerarchie ▶ Usa gli anchor link interni per guidare le persone attraverso contenuti lunghi ▶ Via libera a liste e screenshot
19. 19 La gerarchia dei tag header Fonte: 5 most annoying website features I face as a blind person every single day
20. 20 Fonte: Help Center Intercom Introduci il tuo prodotto
21. 21 Crea delle categorie Fonte: HelpScout Docs
22. 22 Un testo ordinato Fonte: HelpScout Docs
23. 23 Un titolo H1 chiaro ➜ Fonte: HelpScout Docs Un testo ordinato
24. 24 Blocchi di testo che alleggeriscono la lettura Fonte: HelpScout Docs Un testo ordinato
25. 25 Anchor links per guidare chi legge attraverso il documento Fonte: HelpScout Docs Un testo ordinato
26. 26 Fonte: WooCommerce Docs Istruzioni passo-passo
27. 27 Una lista numerata come guida passo-passo Fonte: WooCommerce Docs Istruzioni passo-passo
28. 28 Uno screenshot con frecce che dirigono lo sguardo sui punti della lista Fonte: WooCommerce Docs Istruzioni passo-passo
29. Rendere i contenuti accessibili 29
30. 30 “Solve for one, extend to many by focusing on what’s universally important to all humans” Fonte: Inclusive Design by Microsoft Tutti noi abbiamo capacità e limiti a queste capacità, tutti possiamo sperimentare l'esclusione mentre interagiamo con determinati prodotti. Così come quando creiamo un sito web o un prodotto digitale, anche i contenuti (testuali e non) devono tenere conto dell’accessibilità.
31. 31 ▶ Alternative ▶ Linguaggio ▶ Link Fonte: Inclusive Design by Microsoft Contenuti accessibili
32. 32 Alternative per contenuti non testuali Offri delle alternative per tutti i contenuti non testuali che compaiono nella documentazione: ▶ Immagini ▶ Audio e video ▶ Grafici In questo modo i tuoi contenuti sono sempre fruibili, a prescindere dalla tecnologia usata da chi li consulta.
33. 33 Fonte: Mailchimp Docs Alternative alle immagini Il testo alternativo all’immagine (alt-text) deve essere appropriato alla tipologia di immagine che stai sostituendo: ▶ Funzionale ▶ Informativa ▶ Decorativa
34. 34 Alternative alle immagini Il testo alternativo all’immagine (alt-text) deve essere appropriato alla tipologia di immagine che stai sostituendo: ▶ Funzionale alt="Facebook" Fonte: Mailchimp
35. 35 Fonte: Hubspot Docs Alternative alle immagini Il testo alternativo all’immagine (alt-text) deve essere appropriato alla tipologia di immagine che stai sostituendo: ▶ Informativa alt="Templates and modules are at the intersection between developers and marketers"
36. 36 Alternative alle immagini Il testo alternativo all’immagine (alt-text) deve essere appropriato alla tipologia di immagine che stai sostituendo: ▶ Decorativa alt="" Fonte: Work at Dropbox
37. 37 Fonte: FutureLearn - Screenshot dal corso "Introduction to Content Design" Alternative ai video ▶ Assicurati di aggiungere i sottotitoli ▶ Se il video contiene molti passaggi non commentati, aggiungi una trascrizione
38. 38 Fonte: Mailchimp Docs Linguaggio non direzionale Evita il linguaggio direzionale come “vedi la figura a sinistra”. Se la persona che legge la documentazione è su mobile, una frase del genere non ha senso, poiché i contenuti sono ordinati in modo diverso che da desktop.
39. 39 Fonte: “Click Here” to “Read More”: Why Ambiguous Links are Problematic Link descrittivi Quando aggiungi un link, non usare anchor text generici come “clicca qui”. Meglio usare parole più descrittive che spieghino il contenuto del link o l’azione insita nel link.
40. 3. Risorse utili da consultare in ogni momento 40
41. 41 ▶ Grammarly ▶ Hemingway Editor
42. 42 ▶ Words to Use ▶ Reverso Context
43. Grazie! Domande? Puoi scrivermi anche un’email: ciao@aliceorru.me 43