Centro di conoscenza

Come scrivere ottimi articoli

Permetti ai tuoi colleghi di dare il meglio, con una documentazione di livello mondiale.
Top banner

Scrivere sui prodotti e le funzionalità di Clerk è una parte fondamentale per rendere le persone di successo. I nostri colleghi si affidano al Knowledge Center per qualsiasi informazione di cui hanno bisogno sui nostri prodotti quando parlano con prospect, clienti e partner.

È nostro sacro dovere (debole coro angelico) mantenerlo facile da navigare e fare in modo che ogni articolo sia super ben descritto così che resti uno strumento essenziale per colmare il divario tra Prodotto e il resto dell’azienda.

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

Stile di Scrittura #

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

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

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

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

Sì, ma li producono anche con una qualità super definita e coerente che crea gruppi quasi 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.

Deve essere costantemente fantastico, perché colleghi e clienti siano religiosamente coinvolti nell’utilizzarlo, proprio come vogliamo noi ;)

Vediamo come puoi farlo.

Voce & Tono #

Quando scriviamo per i nostri clienti, ci concentriamo nel rendere tutto chiaro e facile da capire. Il nostro obiettivo è fornire informazioni utili senza confusioni. Evitiamo un linguaggio complicato e ci assicuriamo che ogni passo 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 utenti. Lo facciamo grazie a un’ottima stesura e a una struttura chiara.

L’umorismo è benvenuto, ma solo se si adatta naturalmente. Soprattutto, vogliamo aiutare i nostri clienti senza essere paternalistici o dando per scontato che sappiano già tutto.

  1. Mantieni la Semplicità: Usa un linguaggio chiaro e facile da capire. Evita frasi lunghe e confuse e parole complicate. Usa la forma attiva per rendere il testo diretto e semplice da leggere.

  2. Sii Rispettoso: Scrivi trattando il lettore come tuo pari. Non dare per scontato che sappia già qualcosa. Fornisci tutti i dettagli necessari, con link ad approfondimenti se serve.

  3. Sii Chiaro e Utile: Concentrati nel fornire informazioni utili invece di lunghe spiegazioni. Guida il lettore passo dopo passo, e pensa a cosa potrebbe cercare per trovare facilmente le risposte.

  4. Usa l’Umorismo con Cautela: L’umorismo va bene se viene naturale, ma non deve mai essere forzato. Se non sei sicuro che funzioni, lascialo perdere. Concentrati sull’essere utile e chiaro.

Il nostro tono è informale con un forte focus sulla chiarezza. L’umorismo è incoraggiato, ma solo se si integra con la mentalità che ha l’utente durante la lettura. Pensa a perché gli utenti sono qui. Se stanno leggendo un articolo che spiega come funziona Search, probabilmente sono in una fase di scoperta e l’umorismo può funzionare bene.

Se invece stanno leggendo una FAQ o un articolo di troubleshooting, probabilmente sono già infastiditi da un problema e hanno solo bisogno di una soluzione chiara. La mentalità conta ;)

Quando usi l’umorismo, rendilo nerd: amiamo citazioni da 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, pensa a quale di questi tipi soddisfa meglio il bisogno dell’utente.

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 guide dettagliate del backend, ma spiegano chiaramente come funziona ogni parte.

Esempi:

How-Tos #

Spiega come ottenere un certo risultato. Richiedono una guida step-by-step che spiega esattamente quali pulsanti cliccare e le configurazioni da seguire. I lettori di solito cercano di ottenere qualcosa di specifico leggendo questi articoli.

Esempi:

FAQs / Troubleshooting #

Spiega le soluzioni più probabili alle domande o ai problemi comuni. I lettori spesso sono frustrati perché qualcosa non funziona come previsto. Questi articoli devono essere chiaramente etichettati con la domanda che il lettore potrebbe avere in mente, e offrire chiare spiegazioni su come risolvere il problema.

Non si tratta mai di articoli singoli, ma vengono raccolti sotto la FAQ di uno specifico prodotto, funzionalità o integrazione.

Esempi:

Introduzioni #

Hai notato come questo articolo e la sezione Stile di Scrittura iniziano con una piccola introduzione? Hai visto cosa hanno ottenuto?

Le introduzioni servono a spiegare perché qualcosa è importante da leggere. Serve a catturare l’attenzione del lettore e fargli capire rapidamente se ha trovato ciò che cercava.

Un’introduzione non deve essere troppo lunga, ma deve dare al lettore il contesto di ciò che sta per leggere.

Includi sempre un’intro all’inizio degli articoli, e quando inizi una nuova sezione con un titolo h2.

Titolo & Descrizione #

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

Un buon titolo è “Omnisearch”. Una versione pessima è “La nostra funzionalità Omnisearch”. Contiene troppe parole inutili e rende più difficile la navigazione della struttura del menu.

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

Le descrizioni degli articoli devono essere una singola frase che aggiunge contesto all’articolo. Aiuta i lettori a capire se l’articolo è ciò che cercavano. Evita di ripetere il titolo nella descrizione: deve integrarlo, non duplicarlo.

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

Una descrizione cattiva invece è: “Omnisearch è una nuova funzione nel nostro prodotto di ricerca”. Ripete il nome e il contesto della funzione, già chiaro dal menu del Knowledge Center.

Intestazioni #

Sono fondamentali per rendere gli articoli facili da scorrere e navigare. Usale per separare chiaramente le diverse parti. Le intestazioni non devono superare le 3 parole.

Le intestazioni sono gerarchiche, e si usano sempre in questo ordine:

  • h1: Usato solo per il 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 usate automaticamente per creare l’Indice dei Contenuti.

Paragrafi #

Quando scriviamo gli articoli, vogliamo che i lettori possano navigarli e capirli facilmente. Alla fine, raramente leggeranno tutto l’articolo, ma scorreranno alla ricerca della parte di cui hanno bisogno.

Il paragrafo ideale è tra 1 e 3 righe. Paragrafi più lunghi diventano muri di testo. Quando scrivi, assicurati che siano facilmente scansionabili aggiungendo un’interruzione di riga almeno ogni tre righe (considerando un laptop da 13 pollici).

Non è un requisito vincolante, ma una buona regola empirica. Il nostro cervello guarda grandi blocchi di testo e pensa siano difficili da leggere anche se non lo sono.

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


Quando scriviamo gli articoli, vogliamo che i lettori possano navigarli e capirli facilmente. Alla fine, raramente leggeranno tutto l’articolo, ma scorreranno alla ricerca della parte di cui hanno bisogno. Il paragrafo ideale è tra 1 e 3 righe. Paragrafi più lunghi diventano muri di testo. Quando scrivi, assicurati che siano facilmente scansionabili aggiungendo un’interruzione di riga almeno ogni tre righe (considerando un laptop da 13 pollici). Non è un requisito vincolante, ma una buona regola empirica. Il nostro cervello guarda grandi blocchi di testo e pensa siano difficili da leggere anche se non lo sono. Per vedere la differenza, guarda la sezione sopra, dove sono state aggiunte le interruzioni di riga. Più facile da leggere, giusto?

Ogni volta abbia senso, includi link ad altre parti del Knowledge Center. Ricorda che l’utente dovrebbe trovare tutto ciò che serve in qualsiasi articolo, quindi spesso vale la pena almeno riassumere i punti prima di rimandare a un altro articolo con più informazioni.

Esempio:

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

Screenshot #

Utilizziamo Brandbird per creare screenshot accattivanti. Includi sempre uno sfondo a buon contrasto che non distragga, ma valorizzi lo screenshot.

Gli screenshot sono importanti perché mostrano al lettore che si trova nel punto giusto del nostro backend. Il loro scopo principale è fornire contesto, non mostrare tutte le interazioni. La stesura del testo si occupa di quello.

Come regola, usa al massimo uno screenshot o un video contestuale vicino all’inizio di un articolo. Alcuni articoli non hanno bisogno di elementi visivi. Inserisci un’immagine nel corpo solo quando spiega qualcosa che il testo non può spiegare altrettanto chiaramente, come ad esempio un diagramma della configurazione DNS.

Guarda come Linear usa screenshot con parsimonia e li integra con ottima scrittura.

Uno screenshot deve mostrare abbastanza della pagina per orientare il lettore. Seguilo con un testo che spiega i passaggi da compiere o le funzionalità disponibili.

Per esempio, invece di mostrare tre immagini separate per HTML, CSS e Sub-Designs, mostrane una panoramica utile vicino all’inizio dell’articolo. Le annotazioni possono chiarire le aree importanti.

Video #

Usiamo Loom o Tella per registrare video. Utilizza le rispettive funzioni Embed e ricordati di scegliere sempre la versione Responsive. Possono essere aggiunti direttamente in un articolo così:

I video sono ottimi per mostrare chiaramente tutti gli aspetti di una funzione o come eseguire qualcosa di specifico. Si integrano bene alle guide, perché spesso i lettori partono guardando il video e poi consultano l’articolo per riferimento.

Se il video è il principale elemento visivo dell’articolo, mettilo in alto invece di aggiungere uno screenshot contestuale separato.

I video però non devono mai sostituire il testo scritto, quindi tutto quello che mostri nel video va anche spiegato in forma testuale.

Quando registri i video, passa per i punti in ordine cronologico nello stesso ordine dell’articolo, così sarà più facile seguirli.

Voci di Menu #

Organizziamo il Knowledge Center in modo logico, generalmente seguendo l’ordine in cui le funzioni vengono mostrate nel nostro backend.

Solo gli articoli validi per tutti i clienti devono avere una loro pagina. Qualsiasi caso limite va inserito nelle FAQ dell’aspetto rilevante.

Esempi:

  • Gli articoli che spiegano come funziona Omnisearch sono utili a tutti i clienti che usano il prodotto e quindi hanno il loro articolo.
  • Il debug sul perché gli ordini tracciati non compaiono nel dashboard è un caso limite, e si trova nelle FAQ per Any (Webshop)

Hugo #

L’intero Knowledge Center è scritto usando Hugo Themes – un leggero sistema di template che genera file HTML statici dal Markdown. Ci permette di lavorare solo nella cartella /content e Hugo rende tutto in modo eccellente tramite il nostro tema.

Vedi come iniziare con Hugo nel file README.md che trovi nella root oppure nel repo su Github.

Cartelle & file #

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

Le traduzioni sono gestite con Localazy come spiegato nel file README.md nella root.

La struttura delle cartelle rispecchia da vicino il menu, perché Hugo genera il menu in base allo schema delle cartelle qui sotto.

Ogni articolo ha una cartella sua, che contiene un file _index.md da modificare. L’underscore è obbligatorio perché Hugo capisca che questa è una landing page.

Per default, il titolo dell’articolo è dato dal nome della cartella, quindi sceglilo con cura seguendo gli esempi esistenti. Il titolo può essere modificato nel front matter di ogni 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 ciascun articolo viene 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 #

Sono i meta-dati che puoi aggiungere agli articoli, come titolo, descrizione, alias (redirect), categorie e altro.

Il front matter si trova sempre all’inizio dell’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 è incluso, si usa il nome della cartella in formato titlecase.
  • onPageTitle: Un titolo mostrato solo nella pagina dell’articolo, non nel menu. Utile per la SEO, ad esempio il titolo pagina può essere “How Product Logics Work”, mentre in menu resta “Logics”.
  • description: Mostrata sotto il titolo nella pagina articolo. È richiesta perché dà valore e 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 in passato. Hugo li usa per il redirect ed evitare errori 404. Se cambi nome alla cartella di un articolo, devi aggiungere l’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 permette di concentrarti solo sul contenuto, senza dover lottare anche con HTML e CSS.

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

È davvero intuitivo da usare. Se ti serve un cheat sheet, guarda il sito ufficiale.

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

Intestazioni #

Possono essere aggiunte usando un certo numero di # seguiti dal testo del titolo.

Il numero di cancelletto decide il livello dell’intestazione:

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

Paragrafi #

Qualsiasi testo sulla stessa riga o quella successiva viene visualizzato come un unico paragrafo. Inserire 1 riga vuota separa i paragrafi:

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

Questo testo riceve il suo paragrafo.

Si aggiungono semplicemente evidenziando il testo desiderato e racchiudendolo tra parentesi quadre seguito da una parentesi tonda col link

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

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

Puoi usare anchor per mandare i lettori a parti specifiche di articoli lunghi, usando # seguito dall’ID dell’intestazione.

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

Si può usare per riferimenti all’interno dello stesso articolo o verso altri articoli includendo anche il percorso relativo:

Check the [For Developers](#for-developers) section further down.

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

Immagini #

Usiamo uno shortcode personalizzato per mostrare screenshot negli articoli.

Le immagini vanno sempre esportate come .webp da Brandbird per mantenere alta qualità e peso ridotto.

Le immagini sono salvate nella stessa cartella del tuo _index.md per tenerle organizzate.

La sintassi dello shortcode è:

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

Scrivi sempre un testo alternativo per l’immagine, così i motori di ricerca capiscono cosa viene mostrato.

Sfondi Automatici #

Le immagini ricevono automaticamente uno sfondo decorativo. Questo crea un effetto fluttuante con un’ombra leggera, rendendo gli screenshot più accattivanti.

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

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

Usa "no-background" quando lo screenshot già include bordo o sfondo personalizzato.

Riferimenti UI #

Il Knowledge Center è tradotto automaticamente, quindi per evitare di tradurre le voci di menu, usiamo uno shortcode specifico per i riferimenti all’interfaccia utente.

La sintassi è:

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

Se serve inserire un riferimento UI in un titolo, la sintassi è leggermente diversa perché Hugo rende i titoli in modo diverso rispetto al testo:

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

Il risultato mostrerà un testo in grassetto che resta uguale in tutte le lingue: Search > Designs > New Design > Omnisearch

Callout #

Sono riquadri colorati per evidenziare punti importanti. Usali con parsimonia e solo quando qualcosa è davvero importante.

Significa che un singolo articolo non dovrebbe contenere più di 1 di ciascuno di questi, altrimenti l’articolo diventa troppo complesso.

La sintassi è:

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

Ci sono tre tipi di callout:

Info su qualcosa che è bene sapere, come un template suggerito.
Warning relativo a qualcosa che potrebbe creare problemi, come dimenticare di salvare prima di uscire da una pagina.
Danger per qualcosa che potrebbe compromettere tutto, ad esempio aggiornare un’estensione senza prima fare un backup.

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

Blocchi di codice #

Esistono due varianti: inline e a blocco.

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

I blocchi di codice veri e propri si creano racchiudendo il codice con 3 backtick all’inizio e alla fine, e aggiungendo il linguaggio per la colorazione:

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

Inizia a scrivere #

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

C’è molto da assorbire in questo articolo, e probabilmente domani non ne ricorderai metà. Fai una pausa, mangia qualcosa, e rileggilo.

Poi trova un articolo nel Knowledge Center che secondo te si può migliorare, e riscrivilo seguendo queste linee guida. Tieni aperta questa guida durante la scrittura, così puoi consultarla.

Quando hai fatto il meglio che puoi, cerca un feedback da un collega – non serve più di 10 minuti, e loro potranno notare aspetti che magari tu non hai visto.

Tutti diventano monotematici mentre scrivono, quindi il feedback è cruciale per ottenere il miglior risultato possibile.

Buona scrittura!

Questa pagina è stata tradotta da un'utile intelligenza artificiale, quindi potrebbero esserci errori linguistici. Grazie per la comprensione.