Come scrivere ottimi articoli

È nostro sacro dovere (coro angelico in sottofondo) mantenerlo facile da navigare e descrivere ogni articolo in modo super dettagliato, così che 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 la documentazione? Butti giù due parole che mostrano dove andare e aggiungi uno screenshot, giusto?

Beh, sì e no. In realtà, soprattutto no.

Come scriviamo la documentazione è tanto cruciale quanto cosa scriviamo. È fondamentalmente la UX del nostro lavoro.

Dopotutto, pensa alle principali ragioni per cui Apple è una delle aziende di elettronica leader al mondo. Producono solo telefoni e portatili, no?

Sì, ma li realizzano anche con una qualità estremamente elevata e costante che crea veri e propri gruppi religiosi di persone fidelizzate al loro ecosistema.

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

Questo deve essere costantemente eccezionale, affinché colleghi e clienti siano investiti religiosamente nell’utilizzarlo, proprio come vogliamo noi ;)

Scopriamo come puoi fare tutto questo.

Voice & Tone #

Quando scriviamo per i nostri clienti, ci concentriamo sulla chiarezza e sulla semplicità. Il nostro obiettivo è fornire informazioni utili senza confondere. Evitiamo un linguaggio complicato e spieghiamo ogni passaggio necessario.

Scriviamo sia per lettori tecnici sia non tecnici, quindi i nostri articoli devono essere semplici ma informativi per entrambi i tipi di utenti. Lo facciamo con una grande cura nei testi e una struttura chiara.

L’umorismo è benvenuto, ma solo se si inserisce in modo naturale. Soprattutto, vogliamo aiutare i nostri clienti senza essere condiscendenti o presumere che sappiano già tutto.

1. Semplicità: Usa un linguaggio chiaro e facile da capire. Evita frasi lunghe e confuse o parole complicate. Utilizza la forma attiva per rendere la scrittura più diretta e scorrevole.

2. Rispetto: Scrivi rivolgendo al lettore come a un pari. Non dare per scontato che sappiano già le cose. Fornisci tutti i dettagli necessari, con link ad approfondimenti quando serve.

3. Chiarezza e utilità: Concentrati nel fornire informazioni utili, non spiegazioni troppo lunghe. Guida i lettori passo per passo e pensa a ciò che potrebbero cercare per aiutarli a trovare facilmente le risposte.

4. Umorismo con cautela: L’umorismo è ottimo se è naturale, ma non deve mai essere forzato. Se non sei sicuro che funzioni, lascialo fuori. Mantieni sempre la priorità su utilità e chiarezza.

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

Se invece sta sfogliando FAQ o articoli di troubleshooting, probabilmente è già infastidito da un problema e vuole solo una soluzione chiara. La mentalità conta ;)

Quando usi l’umorismo, che sia nerd - Adoriamo i riferimenti a Star Wars, Il Signore degli Anelli, Matrix e altri fenomeni geek-culture. Spesso funzionano bene negli esempi di codice, come vedrai ;)

Tipi di articoli #

Quando scrivi, considera quale di questi tipi risponde meglio alle esigenze dell’utente.

Informational #

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

Esempi:

• Cookieless
• Dashboard
• Conversations

How-Tos #

Spiegano come ottenere un determinato risultato. Richiedono una guida passo-passo spiegando esattamente quali pulsanti cliccare e quali configurazioni eseguire. I lettori di solito cercano di ottenere qualcosa di specifico.

Esempi:

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

FAQs / Troubleshooting #

Spiega le soluzioni più probabili a domande o problemi comuni. I lettori sono spesso già frustrati, perché qualcosa non funziona come dovrebbe. Devono essere chiaramente etichettati con la domanda che l’utente potrebbe avere e offrire spiegazioni chiare su come risolvere.

Questi non sono mai articoli singoli, ma raccolti sotto FAQ relative al prodotto, funzionalità o integrazione specifica.

Esempi:

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

Intros #

Hai notato come questo articolo e la sezione Writing Style iniziano con una piccola introduzione? Hai visto cosa hanno ottenuto?

Le intro servono a spiegare perché qualcosa è importante da leggere. Si tratta di catturare subito l’attenzione del lettore e aiutarlo a capire al volo se ha trovato il contenuto giusto.

Le introduzioni non devono essere troppo lunghe, ma devono dare contesto su cosa si sta per leggere.

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

Title & Description #

Il titolo dell’articolo deve sempre essere chiaro e conciso. Un buon titolo contiene al massimo 3 parole, idealmente solo 1.

Un buon titolo è “Omnisearch”. Una versione meno buona è “La nostra funzione Omnisearch”: aggiunge parole inutili e rende più difficile navigare nel menu.

I titoli brevi sono ottimi perché si sfogliano facilmente e, abbinati a una struttura di menu logica, manteniamo il Knowledge Center facile da esplorare.

Le descrizioni degli articoli dovrebbero essere una sola frase che aggiunge contesto. Aiuta i lettori a capire se l’articolo è quello che stavano cercando. Evita di ripetere il titolo nella descrizione - dovrebbe aggiungere qualcosa in più.

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

Una cattiva descrizione è: “Omnisearch è una nuova funzione del nostro prodotto search”. Ripete il nome della funzione e la sua posizione nel catalogo, già chiari dal menu del Knowledge Center.

Headings #

Questi sono cruciali per rendere gli articoli facili da scorrere e navigare. Usali per separare chiaramente le varie parti. I titoli hanno al massimo 3 parole.

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

• h1: Solo per il titolo principale
• h2: Sezione principale
• h3: Sottotitolo di h2
• h4: Sottotitolo di h3

Non utilizziamo mai heading inferiori a h4.

Tutti gli h2 e h3 sono usati in automatico per creare l’indice dell’articolo.

Paragraphs #

Quando scriviamo articoli, vogliamo che i lettori possano navigare e capire facilmente. Dopotutto, difficilmente leggeranno tutto il testo, ma scorreranno per trovare le parti utili.

Il paragrafo ideale è lungo da 1 a 3 righe. Paragrafi più lunghi sembrano subito muri di testo. Mentre scrivi, assicurati che sia facile da scorrere inserendo un’interruzione di linea almeno ogni 3 righe (su uno schermo da 13 pollici).

Non è un obbligo tassativo, ma una buona regola pratica. Il nostro cervello tende a considerare i blocchi di testo troppo grandi come difficili da leggere, anche se non lo sono.

Per visualizzare la differenza, controlla qui sotto la sezione senza interruzioni di riga. Più difficile da scorrere, vero?

Quando scriviamo articoli, vogliamo che i lettori possano navigare e capire facilmente. Dopotutto, difficilmente leggeranno tutto il testo, ma scorreranno per trovare le parti utili. Il paragrafo ideale è lungo da 1 a 3 righe. Paragrafi più lunghi sembrano subito muri di testo. Mentre scrivi, assicurati che sia facile da scorrere inserendo un’interruzione di linea almeno ogni 3 righe (su uno schermo da 13 pollici). Non è un obbligo tassativo, ma una buona regola pratica. Il nostro cervello tende a considerare i blocchi di testo troppo grandi come difficili da leggere, anche se non lo sono. Per visualizzare la differenza, guarda la sezione sopra, dove sono state aggiunte le interruzioni di riga. Più facile da leggere, vero?

Links #

Ogni volta abbia senso, includi link verso altre parti del Knowledge Center. Tieni sempre a mente che l’utente dovrebbe avere tutto ciò che gli serve in un singolo articolo, quindi spesso vale la pena almeno riassumere i punti principali, prima di rimandare a un approfondimento.

Esempio:

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

Screenshots #

Usiamo Brandbird per creare screenshot accattivanti. Includi sempre uno sfondo a contrasto per lo screenshot, che non distragga l’attenzione, ma lo valorizzi.

Gli screenshot sono importanti perché mostrano all’utente che è nel punto giusto del nostro backend. Il loro scopo principale è fornire contesto, non mostrare tutte le interazioni. La scrittura si occuperà di quello.

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

Guarda come Linear usa gli screenshot con parsimonia, accompagnandoli con ottimi testi.

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

Ad esempio, piuttosto che mostrare 3 immagini diverse per HTML, CSS e Sub-Designs separatamente, meglio una sola all’inizio del paragrafo che le mostri tutte. Annotazioni sono anche benvenute per chiarire parti dell’immagine.

Videos #

Usiamo Loom o Tella per registrare i video. Usa le funzioni Embed e ricordati di selezionare sempre la versione Responsive. Possono essere aggiunti direttamente all’articolo così:

I video sono ideali per mostrare chiaramente le funzionalità o spiegare come eseguire qualcosa di specifico. Sono un ottimo complemento alle guide, perché chi legge può spesso guardare prima il video e poi usare l’articolo per riferimento.

Tuttavia i video non devono mai sostituire il testo scritto, quindi tutto ciò che è mostrato in video deve essere anche spiegato nel testo.

Quando registri, segui i punti in ordine cronologico proprio come li hai scritti nell’articolo, così saranno facili da seguire.

Menu Items #

Organizziamo il Knowledge Center in modo logico, generalmente seguendo lo stesso ordine delle funzionalità presenti nel nostro backend.

Solo gli articoli applicabili a tutti i clienti dovrebbero avere una pagina dedicata. Qualsiasi caso limite va inserito tra le relative FAQ.

Esempi:

• Gli articoli che spiegano come funziona Omnisearch riguardano tutti i clienti che usano il prodotto, quindi hanno un proprio articolo.
• Il debug di ordini non tracciati nella dashboard è un caso limite e va inserito nella FAQ per Any (Webshop)

Hugo #

Tutto il nostro Knowledge Center è scritto usando Hugo Themes - Un sistema di template leggero che genera file HTML statici da Markdown. Ci permette di lavorare esclusivamente nella cartella /content e Hugo li renderizza magnificamente tramite il nostro tema.

Vedi come iniziare con Hugo nel file README.md alla radice del progetto o nel repo Github.

Folders & files #

Lavori nella cartella content/en e in quelle integrazioni & platform.

Le traduzioni sono gestite tramite Localazy come vedi dal file README.md nella root.

La struttura delle cartelle rispecchia quella del menu, perché Hugo crea il menu sulla base di ciò che vedi qui sotto.

Ogni articolo è nella propria cartella con un file _index.md da modificare. Il trattino basso deve essere presente perché Hugo riconosca una landing page.

Per default, il titolo di un articolo è preso dal nome della cartella, quindi scegli con cura 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 search)
│        └── writing (questo articolo)	
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
└── hugo.toml         <-- configurazione del sito

L’URL di ogni articolo è generato in base alla struttura delle cartelle fino all’ultimo livello, dove risiede 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 ogni 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 punto menu. Se non presente, viene usato il nome della cartella con la prima lettera maiuscola.
• onPageTitle: Un titolo visualizzato solo nella pagina dell’articolo, non nel menu. Utile per la SEO quando il titolo della pagina può essere “How Product Logics Work”, mentre l’articolo resta elencato come “Logics” nel menu.
• description: Mostrata appena sotto il titolo nella pagina. È necessaria perché offre un importante contesto al lettore.
• weight: La posizione dell’articolo nel menu. Più basso il numero, più in alto viene mostrato.
• aliases: Vecchi URL in cui l’articolo era presente. Hugo li usa per fare redirect ed evitare errori 404. Se cambi mai il nome cartella di un articolo, dovrai aggiungere il precedente URL come alias qui. Ma in generale, non cambiare i nomi cartelle. Usa invece title.

Markdown #

Un fantastico linguaggio di markup che ti permette di concentrarti solo sul contenuto, senza complicarti la vita con HTML e CSS.

I file Markdown vengono convertiti in HTML visibile al cliente.

È molto intuitivo da usare. Se ti serve una guida rapida, dai un’occhiata al sito ufficiale.

Qui sotto trovi le regole base più comuni.

Headers #

Puoi aggiungerli usando un numero di # seguito dal testo del titolo.

Il numero di hashtag decide il livello del titolo:

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

Paragraphs #

Tutto il testo sulla stessa o sulla riga seguente sarà visualizzato come unico paragrafo. Una riga di spazio tra i blocchi separa i paragrafi:

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

Il testo qui sotto avrà un suo paragrafo.

Links & Anchors #

Puoi aggiungere un link semplicemente selezionando il testo e racchiudendolo tra parentesi quadre, seguito da una parentesi con il link:

... read more about [Content here](/platform/elements/settings/)

Quando fai riferimento ad articoli interni al Knowledge Center, serve solo il percorso relativo come nell’esempio. Per fonti esterne, inserisci l’URL completo.

Puoi usare gli anchor per guidare i lettori a parti specifiche di un articolo, usando il # seguito dall’ID del titolo.

L’ID è una versione semplificata del nome. Es: il titolo “For Developers” avrà ID for-developers.

Si possono usare per riferirsi a header all’interno dello stesso articolo o di altri articoli, includendo anche il percorso relativo:

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

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

Images #

Usiamo uno shortcode personalizzato per mostrare screenshot negli articoli.

Dovresti sempre esportare le immagini in formato .webp da Brandbird per alta qualità e peso ridotto.

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

La sintassi dello shortcode è:

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

Scrivi sempre un alt text, così i motori di ricerca capiscono ciò che mostrano.

Automatic Backgrounds #

Le immagini ricevono automaticamente uno sfondo decorativo. Crea un effetto flottante con un’ombra leggera che rende gli screenshot più accattivanti.

Se un’immagine ha già uno sfondo incluso (ad es. da Brandbird), puoi disattivare lo sfondo automatico aggiungendo "no-background" come terzo parametro:

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

Usa "no-background" se lo screenshot ha già uno sfondo o un bordo personalizzato.

UI references #

Il Knowledge Center viene tradotto automaticamente, quindi per evitare che i menu vengano tradotti usiamo uno shortcode speciale per riferirci ai nomi dell’interfaccia.

La sintassi è:

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

Se devi aggiungere un riferimento UI in un titolo, la sintassi cambia leggermente, perché Hugo gestisce i titoli in modo diverso rispetto al resto del testo:

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

Il risultato sarà un testo in grassetto che resta sempre uguale in tutte le traduzioni: Search > Designs > New Design > Omnisearch

Callouts #

Questi sono box colorati che puoi usare per mettere in evidenza punti importanti. Usali con moderazione, solo quando qualcosa è davvero rilevante.

Questo significa anche che ogni singolo articolo generalmente non deve contenere più di uno di questi per tipo, altrimenti rendono troppo complesso l’articolo.

La sintassi è:

{{< hint info|warning|danger >}}
**Qualcosa**: Da ricordare.
{{< /hint >}}

Ci sono tre tipi di callout:

Info su qualcosa di utile da sapere, come un suggerimento per un template di partenza.

Warning per avvisare di un possibile problema, come dimenticare di salvare prima di uscire da una pagina.

Danger su qualcosa che potrebbe bloccare totalmente la configurazione, come aggiornare un’estensione senza aver fatto un backup.

Usali solo quando serve davvero, secondo la gravità di ciò che spiegano.

Code blocks #

Esistono due varianti: inline e a blocco.

Un inline code block che si crea usando due backtick `come questo`.

I blocchi di codice completi, racchiudendo il codice con 3 backtick all’inizio e fine, specificando il linguaggio:

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

Start writing #

Ora sei pronto a scrivere contenuti di livello mondiale!

Ci sono molte cose da assimilare in questo articolo, e probabilmente domani non ne ricorderai la metà. Fai una pausa, mangia qualcosa e rileggilo.

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

Quando pensi di aver fatto del tuo meglio, chiedi feedback a un collega: non richiede più di 10 minuti e saprà cogliere dettagli che potresti non aver notato.

Tutti abbiamo la “tunnel vision” mentre scriviamo, quindi il feedback è fondamentale per produrre il miglior contenuto possibile.

Buona scrittura!