Scrivere una documentazione tecnica efficace: Lo stai facendo bene? Alice Orrù WordCamp Italia - 17 ottobre 2020

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

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

1. Perché scrivere una documentazione tecnica Partiamo dalla base 4

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

2. Come scrivere la tua documentazione tecnica I consigli di una copywriter 6

Scegliere le parole 7

8 Ascolto Consistenza Chiarezza Risposte Il percorso delle parole

Come parlano le persone che usano il tuo prodotto? Quali termini usano per descrivere i problemi che incontrano? 9 Ascolta il tuo pubblico:

La documentazione tecnica serve a risolvere dubbi, non a far venire altre domande. 10 Scegli parole chiare, semplici, accessibili:

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:

Usa la stessa parola per descrivere un concetto che ripeti spesso. Es. Bacheca WordPress o Cruscotto WordPress? 12 Mantieni la consistenza del linguaggio:

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

Organizzare i contenuti 14

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?

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 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 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 La gerarchia dei tag header Fonte: 5 most annoying website features I face as a blind person every single day

20 Fonte: Help Center Intercom Introduci il tuo prodotto

21 Crea delle categorie Fonte: HelpScout Docs

22 Un testo ordinato Fonte: HelpScout Docs

23 Un titolo H1 chiaro ➜ Fonte: HelpScout Docs Un testo ordinato

24 Blocchi di testo che alleggeriscono la lettura Fonte: HelpScout Docs Un testo ordinato

25 Anchor links per guidare chi legge attraverso il documento Fonte: HelpScout Docs Un testo ordinato

26 Fonte: WooCommerce Docs Istruzioni passo-passo

27 Una lista numerata come guida passo-passo Fonte: WooCommerce Docs Istruzioni passo-passo

28 Uno screenshot con frecce che dirigono lo sguardo sui punti della lista Fonte: WooCommerce Docs Istruzioni passo-passo

Rendere i contenuti accessibili 29

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 ▶ Alternative ▶ Linguaggio ▶ Link Fonte: Inclusive Design by Microsoft Contenuti accessibili

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 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 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 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 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 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 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 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.

3. Risorse utili da consultare in ogni momento 40

41 ▶ Grammarly ▶ Hemingway Editor

42 ▶ Words to Use ▶ Reverso Context

Grazie! Domande? Puoi scrivermi anche un’email: ciao@aliceorru.me 43