Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Come scrivere una documentazione tecnica efficace

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.

14b18f0c03076cae90a2b9f6b139cefd?s=128

Alice Orrù

October 17, 2020
Tweet

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