Come scrivere ottimi articoli

È nostro sacro dovere (coro angelico in lontananza) mantenerlo facile da navigare e rendere ogni articolo estremamente ben descritto, affinché rimanga uno strumento essenziale per colmare il divario tra Product e il resto dell’azienda.

Ogni articolo che scrivi potrà essere letto centinaia, se non migliaia di volte, quindi devi essere ossessionato dalla qualità.

Writing Style #

Quanto può essere difficile scrivere documentazione? Scrivi qualche parola che mostra dove andare e aggiungi uno screenshot, giusto?

Beh, sì e no. In realtà, più no che sì.

Come scriviamo la documentazione è importante quanto cosa scriviamo. È sostanzialmente la UX del nostro lavoro.

Dopotutto, pensa ai motivi principali per cui Apple è una delle aziende leader nel settore dell’elettronica nel mondo. Producono solo telefoni e laptop, giusto?

Sì, ma li producono anche con una qualità estremamente nitida e coerente che crea quasi gruppi religiosi di persone che giurano fedeltà al loro ecosistema.

Il design conta, e il design di un articolo del Knowledge Center è lo stile di scrittura.

Questo deve essere sempre fantastico, affinché colleghi e clienti siano investiti religiosamente nell’utilizzarlo, proprio come vogliamo che siano ;)

Scopriamo insieme come puoi riuscirci.

Voice & Tone #

Quando scriviamo per i nostri clienti, ci concentriamo nel rendere le cose chiare e facili da capire. Il nostro obiettivo è fornire informazioni utili senza confonderli. Evitiamo un linguaggio complicato e ci assicuriamo che ogni passaggio necessario sia spiegato.

Scriviamo sia per utenti tecnici che non tecnici, quindi i nostri articoli devono essere semplici ma informativi per entrambi. Ci riusciamo offrendo testi eccellenti e una struttura chiara.

L’umorismo è il benvenuto, ma solo se naturale. Ancora più importante, vogliamo aiutare i nostri clienti senza trattarli dall’alto in basso o presupporre che sappiano tutto.

1. Sii Semplice: Usa un linguaggio chiaro e facile da capire. Evita frasi lunghe e complesse e parole difficili. Usa la forma attiva per rendere il testo diretto e facile da leggere.

2. Sii Rispettoso: Scrivi in modo da trattare il lettore da pari. Non dare per scontato che sappiano già tutto. Fornisci tutti i dettagli necessari, con link ad altre informazioni se necessario.

3. Sii Chiaro e Utile: Concentrati nel fornire informazioni utili invece di spiegazioni prolisse. Guida i lettori passo dopo passo e pensa a cosa potrebbero cercare in modo che possano trovare facilmente le risposte.

4. Usa l’Umorismo con Cautela: L’umorismo è fantastico se naturale, ma non dovrebbe mai essere forzato. Se non sei sicuro che funzioni, lascia perdere. Concentrati sull’essere utile e chiaro.

Il nostro tono è informale, con grande attenzione alla chiarezza. L’umorismo è incoraggiato ma solo se si adatta allo stato d’animo dell’utente mentre legge. Pensa al motivo per cui gli utenti sono qui. Se un utente legge un articolo che spiega come funziona Search, probabilmente è in modalità di scoperta, e l’umorismo può funzionare bene.

Tuttavia, se stanno leggendo FAQ o articoli di troubleshooting, probabilmente sono già infastiditi da un problema e hanno solo bisogno di una soluzione chiara. Lo stato d’animo conta ;)

Quando si usa l’umorismo, che sia nerd: amiamo i riferimenti a Star Wars, Il Signore degli Anelli, Matrix e altri fenomeni della cultura geek. Spesso funzionano molto bene negli esempi di codice, come vedrai ;)

Tipi di articoli #

Quando scrivi, considera quale di questi tipi risolve meglio la necessità dell’utente.

Informativo #

Spiega i concetti di un prodotto o una funzione. I lettori sono solitamente in modalità scoperta e vogliono capire come funziona. Questi articoli non includono passaggi o istruzioni dettagliate sul backend, ma spiegano chiaramente come funziona ogni parte.

Esempi:

• Cookieless
• Dashboard
• Conversations

How-Tos #

Spiega come raggiungere uno specifico risultato. Richiedono una guida passo-passo che spiega esattamente quali pulsanti cliccare e quali configurazioni affrontare. I lettori cercano di ottenere qualcosa di specifico.

Esempi:

• Get Started on Shopify
• Recommendations Best Practices
• Adding a new Store

FAQ / Troubleshooting #

Spiega le soluzioni più probabili alle domande o ai problemi comuni. I lettori sono spesso un po’ frustrati quando cercano queste soluzioni, perché qualcosa non funziona come previsto. Questi articoli devono essere chiaramente etichettati con la domanda che il lettore si pone, e fornire spiegazioni chiare su come risolvere il problema.

Non sono mai articoli singoli, ma vengono raccolti nelle FAQ per un determinato prodotto, funzionalità o integrazione.

Esempi:

• Any Webshop FAQ
• Lightspeed 429 Error
• Magento 2 403 Forbidden Error

Introduzioni #

Hai notato come questo articolo e le sezioni Writing Style iniziano con una breve introduzione? Hai visto cosa hanno ottenuto?

Le introduzioni servono a spiegare perché vale la pena leggere qualcosa. È questione di catturare l’attenzione del lettore e permettergli di individuare rapidamente se ha trovato il contenuto giusto.

Le introduzioni non devono essere troppo lunghe, ma dovrebbero dare ai lettori il contesto su ciò che stanno per leggere.

Includi sempre le introduzioni all’inizio degli articoli e quando inizi nuove sezioni con un titolo h2.

Titolo & Descrizione #

Il titolo del tuo articolo deve essere sempre chiaro e conciso. Un buon titolo ha massimo 3 parole, idealmente solo 1.

Un buon titolo è “Omnisearch”. Una versione meno buona è “Our Omnisearch Feature”. Aggiunge troppe parole inutili e rende più difficile navigare la struttura del menu.

I titoli brevi funzionano bene perché sono facili da sfogliare e, grazie a una struttura logica del menu, manteniamo il Knowledge Center facile da navigare.

Le descrizioni degli articoli dovrebbero essere una singola frase che aggiunge contesto all’articolo. Aiuta i lettori a verificare se si tratta dell’articolo che cercavano. Evita di ripetere il titolo nella descrizione: dovrebbero completarsi a vicenda.

Una buona descrizione per Omnisearch è: “Una singola finestra a piena pagina che mostra ai tuoi visitatori i risultati più propensi a convertire”. Spiega chiaramente cos’è Omnisearch, in una sola frase.

Un cattivo esempio è: “Omnisearch è una nuova funzionalità del nostro prodotto di search”. Ripete il nome della funzione e la sua collocazione nel nostro catalogo, già chiara dal menu del Knowledge Center.

Titoli #

Sono fondamentali per rendere gli articoli facili da scorrere e navigare. Usali per separare chiaramente le diverse parti. I titoli non devono avere più di 3 parole.

I titoli sono gerarchici e vengono sempre usati nel seguente ordine:

• h1: Solo per il titolo
• h2: Macro-sezione
• h3: Sottotitolo di h2
• h4: Sottotitolo di h3

Non usiamo mai titoli più piccoli di h4.

Tutti gli h2 e h3 vengono usati automaticamente per creare la Table of Contents.

Paragrafi #

Quando scriviamo articoli, vogliamo che i lettori possano navigarli e capirli facilmente. Dopotutto, raramente leggeranno tutto l’articolo, ma lo scorreranno per trovare le parti che gli servono.

Il paragrafo ideale è tra 1 e 3 linee. Paragrafi più lunghi sembrano rapidamente muri di testo. Quando scrivi, assicurati che sia facilmente scorrevole inserendo un’interruzione di riga dopo almeno ogni 3a linea (visualizzata su un laptop da 13 pollici).

Non è un requisito rigoroso ma una buona regola generale. Il nostro cervello tende a vedere blocchi di testo grandi e a dedurre che siano difficili da leggere, anche se non lo sono.

Per visualizzare la differenza, guarda la sezione qui sotto, dove le interruzioni di riga sono state rimosse. Più difficile da scorrere, vero?

Quando scriviamo articoli, vogliamo che i lettori possano navigarli e capirli facilmente. Dopotutto, raramente leggeranno tutto l’articolo, ma lo scorreranno per trovare le parti che gli servono. Il paragrafo ideale è tra 1 e 3 linee. Paragrafi più lunghi sembrano rapidamente muri di testo. Quando scrivi, assicurati che sia facilmente scorrevole inserendo un’interruzione di riga dopo almeno ogni 3a linea (visualizzata su un laptop da 13 pollici). Non è un requisito rigoroso ma una buona regola generale. Il nostro cervello tende a vedere blocchi di testo grandi e a dedurre che siano difficili da leggere, anche se non lo sono. Per visualizzare la differenza, guarda la sezione sopra, dove le interruzioni di riga sono aggiunte. Più facile da leggere, vero?

Link #

Ogni volta che ha senso, includi link ad altre parti del Knowledge Center. Tieni presente che l’utente dovrebbe avere tutto ciò di cui ha bisogno in ogni singolo articolo, quindi spesso vale la pena riassumere i punti prima di collegare un altro articolo per maggiori info.

Esempio:

Prima di continuare, assicurati di creare un nuovo Element. Puoi farlo da Recommendations > Elements > Create New. Leggi di più su Elements qui.

Screenshots #

Utilizziamo Brandbird per creare screenshot accattivanti. Includi sempre uno sfondo a buon contrasto per il tuo screenshot, che non rubi l’attenzione ma lo completi.

Gli screenshot sono importanti perché mostrano al lettore che si trova nel posto giusto del nostro backend. Il loro scopo principale è fornire contesto, non mostrare ogni interazione. Il copywriting si occupa di questo.

Una buona regola è includere al massimo lo stesso numero di immagini che hai di titoli h2 e h3. Anche meno va bene – spesso, meno è meglio per gli screenshot.

Guarda come Linear usa gli screenshot con parsimonia e li accompagna con un ottimo testo descrittivo.

Uno screenshot dovrebbe generalmente mostrare interamente una pagina, seguito da testo che spiega i passaggi da seguire, o le funzioni disponibili.

Ad esempio, invece di mostrare 3 immagini diverse per HTML, CSS e Sotto-Design separatamente, è meglio unirle tutte in un’unica immagine nel paragrafo iniziale. Sono ben accette anche annotazioni per chiarire alcune parti dell’immagine.

Video #

Utilizziamo Loom o Tella per registrare video. Usa le rispettive funzioni Embed e ricorda di scegliere sempre la versione Responsive. Possono essere aggiunti direttamente all’articolo così:

I video sono ottimi per mostrare in modo chiaro tutti gli aspetti di una funzione o come svolgere un’attività specifica. Si combinano bene con le guide, perché i lettori possono spesso iniziare guardando il video e poi usare l’articolo come riferimento.

I video però non devono mai sostituire il testo scritto: tutto ciò che viene mostrato in un video deve essere presente anche in testo.

Quando registri i video, tratta i punti in ordine cronologico come hai scritto l’articolo, in modo che sia facile da seguire.

Voci di Menu #

Organizziamo il Knowledge Center logicamente, e più o meno nello stesso ordine in cui le funzionalità sono mostrate nel nostro backend.

Solo gli articoli applicabili a tutti i clienti devono avere una propria pagina. Qualsiasi edge-case deve essere inserito nelle FAQ per l’aspetto pertinente.

Esempi:

• Gli articoli che spiegano come funziona Omnisearch sono applicabili a tutti i clienti che usano il prodotto, quindi ha un suo articolo.
• Il debug del motivo per cui gli ordini tracciati non sono mostrati nella dashboard è un edge-case e viene trattato nella FAQ di Any (Webshop)

Hugo #

L’intero Knowledge Center è scritto utilizzando Hugo Themes – Un sistema di templating leggero che genera file statici HTML dal Markdown. Ci permette di lavorare completamente nella cartella /content e Hugo rende tutto perfettamente attraverso il nostro tema.

Scopri come iniziare con Hugo nel file README.md che si trova nella cartella root oppure nel repo Github.

Cartelle & file #

Lavori nella cartella content/en e nelle sottocartelle integrations & platform.

Le traduzioni sono gestite da Localazy come puoi vedere dal file README.md nella cartella root.

La struttura delle cartelle rispecchia da vicino la struttura del menu, perché Hugo genera il menu sulla base della struttura delle cartelle che vedi qui sotto.

Ogni articolo si trova in una cartella propria con un file _index.md che devi modificare. L’underscore deve essere incluso affinché Hugo capisca che questa è una landing page.

Di default, il titolo di un articolo è definito dal nome della cartella, quindi scegli bene e segui gli esempi esistenti. Il titolo può essere sovrascritto nel front matter di ciascun articolo.

root/
├── archetypes/
├── assets/
├── content/
│   └── en
│        └── integrations
│            └── act-on
│                └── email-recs
│                    ├── _index.md
│                    ├── screenshot_10535...
│        └── platform
│        └── search (the search page file)
│        └── writing (this article)	
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
└── hugo.toml         <-- site configuration

L’URL di ogni articolo viene generata in base alla struttura delle cartelle fino all’ultimo livello, dove c’è il file _index.md. L’URL per l’esempio sopra è /integrations/act-on/email-recs

Front Matter #

Questi sono i meta-dati che puoi aggiungere agli articoli, come titoli, descrizioni, alias (redirect), categorie e altro.

Il front matter si trova sempre all’inizio di un articolo:

---
title: "Holy Grail"
onPageTitle: "How to find the Holy Grail"
description: "Monty Python's best movie by far"
weight: 3
aliases:
   - /old/path/to/holy-grail
   - /really/old/path/to/holy-grail
---

What is the airspeed velocity of an unladen swallow?...

I front matter più importanti sono:

• title: Un titolo personalizzato per l’articolo, usato per personalizzare il suo punto nel menu. Se non viene incluso, verrà usato il nome della cartella con lettera maiuscola.
• onPageTitle: Un titolo mostrato solo sulla pagina dell’articolo, non nel menu. Utile a fini SEO: il titolo della pagina potrebbe essere “How Product Logics Work”, mentre l’articolo resta “Logics” nel menu.
• description: Mostrata appena sotto il titolo sulla pagina dell’articolo. È obbligatoria perché dà un contesto prezioso al lettore.
• weight: La posizione dell’articolo nel menu. Più basso il numero, più in alto appare nel menu.
• aliases: Vecchi URL dove quest’articolo era situato precedentemente. Hugo li usa per fare redirect ed evitare errori 404. Se mai cambi il nome della cartella di un articolo, dovrai aggiungere il suo URL precedente come alias qui. Ma in generale, non cambiare i nomi delle cartelle. Usa title invece.

Markdown #

Un ottimo linguaggio di markup che ti consente di concentrarti solo sul contenuto, senza dover combattere anche con HTML e CSS.

I file Markdown vengono convertiti in HTML che è poi mostrato al cliente.

È super intuitivo. Se ti serve un promemoria, consulta il sito ufficiale.

Qui sotto trovi le regole di sintassi più comuni che ti servono.

Headers #

Si aggiungono con un certo numero di # seguite dal testo del titolo.

Il numero di cancelletto decide il tipo di header:

h2: ## Shortcodes
h3: ### Their syntaxes
h4: #### A specific syntax

Paragrafi #

Qualsiasi testo sulla stessa riga, o sulla riga successiva, viene mostrato come un unico paragrafo. Aggiungere una riga vuota separa i paragrafi:

Tutto il testo qui è un paragrafo unico.
Anche il testo qui comparirà sulla stessa riga di quello sopra.

Il testo qui viene mostrato in un nuovo paragrafo.

Link & Ancore #

Si aggiungono semplicemente evidenziando il testo che vuoi trasformare in link, racchiudendolo tra parentesi quadre e poi parentesi tonde con il link

... leggi di più su [Content here](/platform/elements/settings/)

Quando fai riferimento ad articoli del Knowledge Center, basta includere il percorso relativo come nell’esempio. Per riferimenti esterni, includi l’URL completo.

Puoi usare le ancore per inviare i lettori direttamente a parti specifiche di articoli lunghi, usando # seguito dall’ID dell’header di riferimento.

L’ID è una versione semplificata del nome. Ad esempio, l’header “For Developers” diventerà for-developers.

Può essere usato sia per riferimenti interni all’articolo stesso, sia per riferirsi ad altri articoli aggiungendo il loro percorso relativo:

Guarda la sezione [For Developers](#for-developers) più giù.

Guarda [Common sync errors for Magento2 qui](/integrations/magento-2/faq/#common-sync-issues).

Immagini #

Usiamo uno shortcode personalizzato per mostrare screenshot negli articoli.

Dovresti sempre esportare le immagini come .webp da Brandbird per mantenere alta la qualità e basso il peso del file.

Le immagini sono salvate nella stessa cartella del file _index.md per rimanere organizzati con l’articolo.

La sintassi dello shortcode è:

{{< image "IMAGE_ALT" "FILENAME.webp" >}}

Scrivi sempre un testo alt per l’immagine, così i motori di ricerca possono capire cosa è mostrato.

Sfondi automatici #

Alle immagini viene applicato automaticamente uno sfondo decorativo. Crea un effetto flottante con un’ombra leggera, rendendo gli screenshot più gradevoli.

Se un’immagine ha già uno sfondo integrato (es. creato su Brandbird), puoi disabilitare lo sfondo automatico aggiungendo "no-background" come terzo parametro:

{{< image "IMAGE_ALT" "FILENAME.webp" "no-background" >}}

Usa "no-background" quando il tuo screenshot ha già un proprio sfondo o bordo stilizzato.

UI references #

Il Knowledge Center è tradotto in automatico, quindi per evitare di tradurre i nomi delle voci di menu, usiamo uno shortcode specifico per riferirci alla nostra interfaccia utente.

La sintassi è:

{{< uiref "Search > Designs > New Design > Omnisearch" >}}

Se ti serve aggiungere un riferimento UI in header, la sintassi è leggermente diversa, perché Hugo processa gli header in modo diverso dal resto del testo:

{{% uiref "Search > Designs > New Design > Omnisearch" %}}

Il risultato apparirà come testo in grassetto che rimane uguale in tutte le traduzioni: Search > Designs > New Design > Omnisearch

Callouts #

Sono box colorati che puoi usare per evidenziare punti importanti. Usali con parsimonia, solo quando qualcosa è davvero importante.

Cioè, ogni articolo singolo non dovrebbe includere più di 1 per ciascun tipo, altrimenti complichi troppo l’articolo.

La sintassi è:

{{< hint info|warning|danger >}}
**Something**: To be aware of.
{{< /hint >}}

Ci sono tre tipi di callouts:

Info su qualcosa di utile da sapere, ad esempio il nostro suggerimento per un template iniziale.

Warning su qualcosa che potrebbe risultare problematico, come dimenticarsi di salvare prima di lasciare una pagina.

Danger su qualcosa che potrebbe rompere completamente una configurazione, come aggiornare un’estensione senza aver prima fatto un backup.

Usali solo quando davvero necessario, secondo la gravità di ciò che spieghi.

Blocchi di codice #

Ne esistono di due tipi: inline e block.

Un inline code block si crea con due backtick `così`.

I blocchi di codice completi si creano racchiudendo il codice con 3 backtick all’inizio e alla fine e specificando il linguaggio per l’evidenziazione:

console.log("What an awesome code example!");

Inizia a scrivere #

Ora sei pronto per iniziare a scrivere contenuti di livello mondiale!

Questo articolo contiene molte informazioni e probabilmente domani non ricorderai nemmeno metà delle cose. Fai una pausa, mangia qualcosa e leggilo di nuovo.

Poi trova un articolo nel Knowledge Center che pensi possa essere migliorato e riscrivilo seguendo queste linee guida. Tieni questa guida aperta mentre scrivi, così puoi consultarla.

Quando hai fatto del tuo meglio, chiedi un feedback a un collega: non deve richiedere più di 10 minuti e potrà individuare aspetti che magari ti erano sfuggiti.

Chiunque lavori sui testi finisce in “tunnel vision”, quindi il feedback è fondamentale per scrivere contenuti della massima qualità.

Buona scrittura!