Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

Scegliere le parole 7

Slide 8

Slide 8 text

8 Ascolto Consistenza Chiarezza Risposte Il percorso delle parole

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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:

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

Organizzare i contenuti 14

Slide 15

Slide 15 text

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?

Slide 16

Slide 16 text

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:

Slide 17

Slide 17 text

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)

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

19 La gerarchia dei tag header Fonte: 5 most annoying website features I face as a blind person every single day

Slide 20

Slide 20 text

20 Fonte: Help Center Intercom Introduci il tuo prodotto

Slide 21

Slide 21 text

21 Crea delle categorie Fonte: HelpScout Docs

Slide 22

Slide 22 text

22 Un testo ordinato Fonte: HelpScout Docs

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

26 Fonte: WooCommerce Docs Istruzioni passo-passo

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

Rendere i contenuti accessibili 29

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

31 ▶ Alternative ▶ Linguaggio ▶ Link Fonte: Inclusive Design by Microsoft Contenuti accessibili

Slide 32

Slide 32 text

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.

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

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

Slide 35

Slide 35 text

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"

Slide 36

Slide 36 text

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

Slide 37

Slide 37 text

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

Slide 38

Slide 38 text

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.

Slide 39

Slide 39 text

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.

Slide 40

Slide 40 text

3. Risorse utili da consultare in ogni momento 40

Slide 41

Slide 41 text

41 ▶ Grammarly ▶ Hemingway Editor

Slide 42

Slide 42 text

42 ▶ Words to Use ▶ Reverso Context

Slide 43

Slide 43 text

Grazie! Domande? Puoi scrivermi anche un’email: [email protected] 43