Come scrivere ottimi articoli

È nostro sacro dovere (coro di angeli in lontananza) mantenere la navigazione semplice e rendere ogni articolo super ben descritto affinché rimanga uno strumento essenziale per colmare il divario tra il Prodotto e il resto dell’azienda.

Ogni articolo che scrivi sarà potenzialmente letto centinaia, se non migliaia di volte, quindi devi ossessionarti per la qualità.

Stile di Scrittura #

Quanto può essere difficile scrivere documentazione? Scrivi alcune parole che mostrano dove andare e aggiungi uno screenshot, giusto?

Beh, sì e no. Per lo più no, in realtà.

Come scriviamo la documentazione è altrettanto cruciale quanto cosa scriviamo. È fondamentalmente l’UX del nostro lavoro.

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

Sì, ma li fanno anche con una qualità super nitida e coerente che crea quasi gruppi religiosi di persone che giurano sul loro ecosistema.

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

Questo deve essere costantemente fantastico, affinché colleghi e clienti siano investiti religiosamente nel suo utilizzo, come vogliamo che siano ;)

Approfondiamo come puoi fare questo.

Voce e Tono #

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

Scriviamo sia per lettori tecnici che non tecnici, quindi i nostri articoli devono essere semplici ma informativi per entrambi i tipi di lettori. Facciamo questo attraverso una grande scrittura e una struttura chiara.

L’umorismo è benvenuto, ma solo se si adatta naturalmente. La cosa più importante è che vogliamo aiutare i nostri clienti senza parlare dall’alto in basso o presumere che sappiano tutto.

1. Mantieni Semplice: Usa un linguaggio chiaro e facile da comprendere. Evita frasi lunghe e confuse e parole complicate. Usa la voce attiva per rendere la scrittura diretta e facile da leggere.

2. Sii Rispettoso: Scrivi in un modo che tratta il lettore come un pari. Non presumere che sappiano già le cose. Assicurati di fornire tutti i dettagli di cui hanno bisogno, con link a ulteriori informazioni se necessario.

3. Sii Chiaro e Utile: Concentrati sul fornire informazioni utili invece di lunghe spiegazioni. Guida i lettori passo dopo passo e pensa a cosa potrebbero cercare affinché possano trovare facilmente le risposte.

4. Usa l’Umorismo con Cautela: L’umorismo è fantastico se si adatta naturalmente, ma non dovrebbe mai essere forzato. Se non sei sicuro che funzioni, lascialo fuori. Mantieni il focus sull’essere utile e chiaro.

Il nostro tono è informale con un grande focus sulla chiarezza. L’umorismo è incoraggiato ma solo se si adatta alla mentalità che un utente ha quando lo legge. Pensa a perché gli utenti sono qui. Se un utente legge un articolo che spiega come funziona la Ricerca, è probabile che sia in una mentalità di scoperta, e l’umorismo può funzionare bene.

Tuttavia, se stanno navigando tra le FAQ o gli articoli di risoluzione dei problemi, è probabile che siano già infastiditi da un problema e abbiano semplicemente bisogno di una soluzione chiara. La mentalità conta ;)

Quando viene usato l’umorismo, rendilo nerd - Adoriamo i riferimenti a Star Wars, Il Signore degli Anelli, Matrix e altri fenomeni della cultura geek. Funziona spesso molto bene negli esempi di codice, come vedrai ;)

Tipi di articoli #

Quando scrivi, considera quale di questi tipi risolve meglio il bisogno degli utenti.

Informativo #

Spiega i concetti di un prodotto o di una funzionalità. I lettori sono solitamente in modalità scoperta quando leggono questi articoli e vogliono capire come funziona. Questi articoli non includono passaggi o guida approfondita attraverso il backend, ma spiegano chiaramente come funziona ogni parte.

Esempi:

• Cookieless
• Dashboard
• Conversazioni

Come-Fare #

Spiega come raggiungere un certo risultato. Questi richiedono una guida passo-passo che spiega i pulsanti esatti che gli utenti dovrebbero cliccare e le configurazioni che dovrebbero seguire. I lettori stanno solitamente cercando di raggiungere qualcosa di specifico quando leggono questi.

Esempi:

• Inizia su Shopify
• Best Practices per le Raccomandazioni
• Aggiungere un nuovo Negozio

FAQ / Risoluzione dei problemi #

Spiega le soluzioni più probabili a domande o problemi comuni. I lettori sono spesso frustrati in qualche misura quando navigano in questi, perché qualcosa non funziona come previsto. Questi dovrebbero essere chiaramente etichettati con la domanda che un lettore avrà in mente e fornire spiegazioni chiare su come risolverlo.

Questi non sono mai articoli individuali, ma sono raccolti sotto FAQ per un prodotto, una funzionalità o un’integrazione specifica.

Esempi:

• FAQ di Any Webshop
• Errore 429 di Lightspeed
• Errore 403 di Magento 2

Introduzioni #

Hai notato come questo articolo e le sezioni sullo Stile di Scrittura iniziano con una piccola introduzione? Hai notato cosa hanno raggiunto?

Le introduzioni riguardano tutto ciò che spiega perché qualcosa è importante da leggere. Si tratta di catturare l’attenzione dei lettori e far loro rapidamente capire se hanno trovato il contenuto o meno.

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

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

Titolo e Descrizione #

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

Un buon titolo è “Omnisearch”. Una versione cattiva è “La nostra funzionalità Omnisearch”. Aggiunge troppe parole non necessarie e rende più difficile navigare nella struttura del menu.

I titoli brevi funzionano bene perché sono facili da sfogliare, e combinati con una struttura di menu logica, 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 convalidare se questo articolo è quello che stavano cercando. Evita di ripetere il titolo nella tua descrizione - dovrebbe complementarlo.

Una buona descrizione per Omnisearch è: “Una finestra a pagina intera che fornisce ai tuoi visitatori i risultati più probabili per convertire”. Elabora chiaramente su cosa sia Omnisearch, in una singola frase.

Una cattiva è: “Omnisearch è una nuova funzionalità nel nostro prodotto di ricerca”. Ripete il nome della funzionalità e il suo posto nel nostro catalogo, che è già chiaro dal menu del Knowledge Center.

Intestazioni #

Queste sono cruciali per rendere gli articoli facili da scorrere e navigare. Usale per separare chiaramente le diverse parti.

Le intestazioni sono gerarchiche e sono sempre usate nel seguente ordine:

• h1: Usato solo dal titolo
• h2: Sezione principale
• h3: Sottotitolo di h2
• h4: Sottotitolo di h3

Non usiamo mai intestazioni più piccole di h4.

Tutte le h2 e h3 vengono utilizzate automaticamente per creare il Sommario.

Paragrafi #

Quando scriviamo articoli, vogliamo che i lettori possano navigare e comprenderli facilmente. Dopotutto, raramente leggeranno l’intero articolo, ma lo sfoglieranno per trovare le parti di cui hanno bisogno.

Il paragrafo ideale è tra 1-3 righe. Paragrafi più lunghi finiscono rapidamente per sembrare muri di testo. Quando scrivi, assicurati che sia facilmente scorrevole aggiungendo interruzioni di riga dopo almeno ogni terza riga (quando visualizzato su un laptop da 13 pollici).

Questa non è una richiesta rigorosa ma una buona regola generale. I nostri cervelli tendono a guardare grandi blocchi di testo e dedurre che siano difficili da leggere, anche se non lo sono.

Per visualizzare la differenza che fa, controlla la sezione qui sotto, dove le interruzioni di riga sono state rimosse. Più difficile da scorrere, giusto?

Quando scriviamo articoli, vogliamo che i lettori possano navigare e comprenderli facilmente. Dopotutto, raramente leggeranno l’intero articolo, ma lo sfoglieranno per trovare le parti di cui hanno bisogno. Il paragrafo ideale è tra 1-3 righe. Paragrafi più lunghi finiscono rapidamente per sembrare muri di testo. Quando scrivi, assicurati che sia facilmente scorrevole aggiungendo interruzioni di riga dopo almeno ogni terza riga (quando visualizzato su un laptop da 13 pollici). Questa non è una richiesta rigorosa ma una buona regola generale. I nostri cervelli tendono a guardare grandi blocchi di testo e dedurre che siano difficili da leggere, anche se non lo sono. Per visualizzare la differenza che fa, controlla la sezione sopra, dove le interruzioni di riga sono state aggiunte. Più facile da leggere, giusto?

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 su un articolo, quindi vale spesso la pena almeno riassumere i punti, prima di collegarsi a un altro articolo con ulteriori informazioni.

Esempio:

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

Screenshot #

Usiamo Brandbird per creare screenshot eleganti. Includi sempre uno sfondo con un buon contrasto per il tuo screenshot, che non rubi attenzione, ma lo completi.

Gli screenshot sono importanti perché mostrano al lettore che si trova nel posto giusto nel nostro backend. Quindi il loro scopo principale è fornire contesto, non mostrare ogni interazione. La scrittura fa questo.

Una buona regola generale è includere al massimo lo stesso numero di immagini che hai di intestazioni h2 e h3. Meno va bene - spesso, meno è di più quando si tratta di screenshot.

Controlla come Linear usa gli screenshot con parsimonia e utilizza una buona scrittura per completarli.

Uno screenshot dovrebbe generalmente coprire l’intera estensione di una pagina, seguito da un testo che spiega i passaggi da seguire o le funzionalità disponibili.

Ad esempio, invece di mostrare 3 immagini diverse per HTML, CSS e Sub-Design separatamente, è meglio una sola che mostri tutto nel paragrafo iniziale. Le annotazioni sono anche benvenute per aiutare a chiarire parti di un’immagine.

Video #

Usiamo Loom o Tella per registrare video. Usa le rispettive funzionalità di Embed e ricorda di scegliere sempre la versione Responsive. Possono essere aggiunti direttamente a un articolo in questo modo:

I video sono ottimi per mostrare chiaramente tutti gli aspetti di una funzionalità o come fare qualcosa di specifico. Completano bene le guide, poiché i lettori possono spesso iniziare guardando il video, prima di utilizzare l’articolo come riferimento.

Tuttavia, i video non dovrebbero mai sostituire il testo scritto, quindi tutto ciò che viene mostrato in un video dovrebbe essere anche scritto nel testo.

Quando registri video, segui i punti in ordine cronologico nello stesso ordine in cui hai scritto l’articolo, in modo che siano facili da seguire.

Elementi di Menu #

Organizziamo il Knowledge Center in modo logico e generalmente nello stesso ordine in cui le funzionalità sono mostrate nel nostro backend.

Solo gli articoli applicabili a tutti i clienti dovrebbero avere le proprie pagine. Qualsiasi caso particolare dovrebbe essere aggiunto sotto le FAQ per l’aspetto pertinente.

Esempi:

• Gli articoli che spiegano come funziona Omnisearch sono applicabili a tutti i clienti che utilizzano il prodotto, quindi hanno il proprio articolo.
• Risolvere perché gli ordini tracciati non vengono mostrati nel dashboard è un caso particolare, ed è messo nelle FAQ di Any (Webshop)

Hugo #

Il nostro intero Knowledge Center è scritto utilizzando i Temi di Hugo - Un sistema di templating leggero che genera file HTML statici da Markdown. Ci consente di lavorare interamente nella cartella /content e Hugo lo rende tutto bellissimo attraverso il nostro tema.

Controlla come iniziare con Hugo nel file README.md trovato nella cartella radice o nel repo di Github.

Cartelle e 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 radice.

L’albero dei file assomiglia strettamente alla struttura del menu, perché Hugo rende il menu in base alla struttura delle cartelle che vedi qui sotto.

Ogni articolo è nella propria cartella con un file _index.md che modifichi. L’underscore deve essere incluso affinché Hugo capisca che questa è una pagina di atterraggio.

Per impostazione predefinita, il titolo di un articolo è definito dal nome della cartella, quindi sceglilo con attenzione e segui gli esempi esistenti. Il titolo può essere sovrascritto nel front matter di ogni articolo.

root/
├── archetypes/
├── assets/
├── content/
│   └── en
│        └── integrations
│            └── act-on
│                └── email-recs
│                    ├── _index.md
│                    ├── screenshot_10535...
│        └── platform
│        └── search (il file della pagina di ricerca)
│        └── writing (questo articolo)	
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
└── hugo.toml         <-- configurazione del sito

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

Front Matter #

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

Il front matter si trova sempre in cima a un articolo:

---
title: "Santo Graal"
onPageTitle: "Come trovare il Santo Graal"
description: "Il miglior film di Monty Python di gran lunga"
weight: 3
aliases:
   - /old/path/to/holy-grail
   - /really/old/path/to/holy-grail
---

Qual è la velocità dell'aria di un rondone non carico?...

Il front matter più importante è:

• title: Un titolo personalizzato per l’articolo, usato per personalizzare il suo punto di menu. Se non è incluso, verrà utilizzato il nome della cartella in maiuscolo.
• onPageTitle: Un titolo mostrato solo sulla pagina dell’articolo, non nel menu. Questo è utile per scopi SEO dove il titolo della pagina potrebbe essere “Come Funzionano le Logiche di Prodotto”, mentre l’articolo è ancora elencato come “Logiche” nel menu.
• description: Mostrato appena sotto il titolo sulla pagina dell’articolo. Questo è richiesto poiché fornisce un contesto prezioso al lettore.
• weight: La posizione degli articoli nel menu. Più basso è il numero, più in alto viene mostrato nel menu.
• aliases: Vecchi URL dove questo articolo è stato precedentemente localizzato. Hugo usa questo per reindirizzare a questa pagina per 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 interamente sul contenuto, piuttosto che anche lottare con HTML e CSS.

I file Markdown vengono tradotti in HTML che viene poi mostrato al cliente.

È super intuitivo da usare. Se hai mai bisogno di un foglio di riferimento, controlla il sito ufficiale.

Di seguito sono riportate le regole di sintassi più comuni di cui hai bisogno.

Intestazioni #

Possono essere aggiunte utilizzando un numero di # seguito dal testo dell’intestazione.

Il numero di hashtag decide l’intestazione:

h2: ## Shortcodes
h3: ### Le loro sintassi
h4: #### Una sintassi specifica

Paragrafi #

Qualsiasi testo sulla stessa o sulla riga successiva viene visualizzato come un singolo paragrafo. Aggiungere 1 riga di spazio tra le righe separa i paragrafi:

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

Il testo visualizzato qui ottiene il proprio paragrafo.

Link e Ancore #

Possono essere aggiunti semplicemente evidenziando il testo per cui vuoi creare un link e racchiudendolo tra parentesi graffe seguite da una parentesi con il link.

... leggi di più su [Content qui](/platform/content/settings/)

Quando si fa riferimento agli articoli nel Knowledge Center, è necessario includere solo il percorso relativo come nell’esempio. Per i riferimenti esterni, includi l’URL completo.

Puoi usare le ancore per inviare i lettori a parti specifiche di articoli più lunghi, usando # seguito dall’ID di un’intestazione nel riferimento.

L’ID è una versione sanitizzata del nome. Ad esempio, l’intestazione “Per Sviluppatori” avrà l’ID for-developers.

Questo può essere utilizzato per fare riferimento alle intestazioni all’interno dell’articolo stesso, o per fare riferimento ad altri articoli includendo anche il loro percorso relativo:

Controlla la sezione [Per Sviluppatori](#for-developers) più in basso.

Controlla [Errori di sincronizzazione comuni per Magento2 qui](/integrations/magento-2/faq/#common-sync-issues).

Immagini #

Usiamo un shortcode personalizzato per mostrare screenshot negli articoli.

Dovresti sempre esportare le immagini come .webp da Brandbird per mantenere alta la qualità e bassa la dimensione del file.

Le immagini sono salvate nella stessa cartella in cui si trova il tuo _index.md per tenerle organizzate con l’articolo.

La sintassi dello shortcode è:

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

Scrivi sempre un testo alternativo per l’immagine, in modo che i motori di ricerca possano capire cosa viene mostrato.

Riferimenti UI #

Il Knowledge Center viene tradotto automaticamente, quindi per evitare di tradurre gli elementi del menu, utilizziamo uno shortcode specifico per fare riferimento alla nostra interfaccia utente.

La sintassi è:

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

Se hai bisogno di aggiungere un riferimento UI in un intestazione, la sintassi è leggermente diversa, perché Hugo rende le intestazioni in un modo diverso rispetto al resto del testo:

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

L’output di questo verrà visualizzato come testo in grassetto che rimane lo stesso attraverso le traduzioni: Search > Designs > New Design > Omnisearch

Callout #

Questi sono riquadri colorati che possono essere utilizzati per evidenziare punti importanti. Dovrebbero essere usati con parsimonia, e solo quando qualcosa è particolarmente importante.

Significa anche che qualsiasi singolo articolo non dovrebbe generalmente contenere più di 1 di ciascuno di questi poiché altrimenti complicano eccessivamente l’articolo.

La sintassi è:

{{< hint info|warning|danger >}}
**Qualcosa**: Da tenere a mente.
{{< /hint >}}

Ci sono tre tipi di callout:

Informazioni su qualcosa che è buono sapere, come il nostro suggerimento per un modello di partenza.

Avviso su qualcosa che potrebbe diventare un problema, come dimenticare di salvare prima di lasciare una pagina.

Pericolo su qualcosa che potrebbe rompere un’intera configurazione, come aggiornare un’estensione senza prima creare un backup.

Usali solo quando è davvero necessario e in base alla gravità di ciò che spiegano.

Blocchi di codice #

Questi vengono in due varianti - inline e blocco.

Un inline code block che è creato usando due backticks `come questo`.

I blocchi di codice completi sono creati avvolgendo il codice con 3 backticks all’inizio e alla fine, e aggiungendo il linguaggio del codice per la sintassi:

console.log("Che esempio di codice fantastico!");

Inizia a scrivere #

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

C’è molto da digerire in questo articolo, e probabilmente non ricorderai metà di esso domani. Fai una pausa, mangia qualcosa e leggilo di nuovo.

Poi trova un articolo nel Knowledge Center che credi possa essere migliore e riscrivilo seguendo queste linee guida. Tieni aperta questa guida mentre scrivi, così puoi fare riferimento ad essa.

Quando hai fatto del tuo meglio, cerca un feedback da un collega - non dovrebbe richiedere più di 10 minuti, e saranno in grado di individuare aspetti che potresti non aver notato.

Tutti tendono a avere una visione ristretta quando scrivono, quindi il feedback è cruciale per scrivere il miglior contenuto possibile.

Buona scrittura!