🛠️
Semplice e minimale, sempre
Lorem ipsum...
This is a link
Style and content guide
This guide provides an overview of the content that should be included in the Zammad documentation and formatting and style guidelines to ensure clarity and readability.
Le prime sezioni riguardano informazioni e regole generali. Segue alla fine una sezione con esempi.
Se hai domande, chiedi pure nella nostra community. Se vuoi contribuire, dai un'occhiata alla nostra pagina dei contributi o apri una issue per iniziare.
Audience assumptions
La documentazione presuppone che gli utenti abbiano una comprensione di base dell'uso dei browser web e familiarità con i concetti comuni del design del software. Ciò significa, ad esempio, che le funzionalità sono descritte in dettaglio, ma non fino al punto di spiegare come aprire un menu a tendina.
Anche l'amministratore di Zammad dovrebbe avere una comprensione tecnica di base e familiarità con i flussi di lavoro e i processi di comunicazione della propria azienda.
Per le istanze self-hosted, gli amministratori di sistema dovrebbero avere familiarità con le basi dell'amministrazione di sistemi Linux. L'accesso al sistema host (ad esempio tramite SSH) e i permessi amministrativi sono dati per scontati.
Contenuto
La documentazione mira a includere informazioni su:
- Come usare Zammad
- Come gestire Zammad come amministratore (ad esempio configurarlo dopo l'installazione, regolare le impostazioni, configurare le funzionalità)
- I diversi modi per installare Zammad
- Guide aggiuntive quando è necessaria la configurazione del sistema (host) e/o di sistemi di terze parti.
Per quanto riguarda il livello di dettaglio, vanno considerate le presupposizioni sul pubblico. Poiché uno degli obiettivi di Zammad è essere intuitivo e user-friendly, non è necessario descrivere ogni clic in dettaglio. Tuttavia, i passaggi importanti devono essere inclusi.
Dato che una documentazione non può coprire tutto, va considerata anche la rilevanza. Se mancano parti con un caso d'uso comune, è opportuno includerle.
Style and rules
Le sezioni seguenti trattano gli aspetti generali da considerare nella scrittura della documentazione. Dopo di esse trovi una sezione con alcuni esempi su come formattare e strutturare il contenuto.
Nozioni di base
- La documentazione è scritta nel linguaggio di markup Markdown. I file sorgente hanno l'estensione
.md. - The system uses VitePress to build the website.
- La lingua dei file sorgente è l'inglese americano.
- La traduzione della documentazione avviene tramite Weblate, vedi la sezione traduzione nella pagina dei contributi per ulteriori dettagli.
Stile
- Usa frasi brevi e chiare e dai priorità alle informazioni rispetto alla complessità.
- Use sentence case for page titles and headings. Capitalize the first word and the first letter of any proper noun (e.g. Zammad, Elasticsearch, Docker, GitLab) and acronym (SLA, SSO, API, JSON, etc.).
- Usa la separazione breadcrumb per percorsi e posizioni con
>come separatore e formatta il percorso in corsivo, ad esempio Impostazioni > Canali > Chat. - Usa l'evidenziazione del codice per enfatizzare i frammenti di programmazione.
- Usa i riquadri info, suggerimento, avviso e pericolo quando necessario.
- Usa un riquadro dettagli quando il contenuto potrebbe non essere rilevante per tutti i lettori o potrebbe interrompere il flusso di lettura.
- Se disponibili, usa le icone per i pulsanti importanti dell'interfaccia utente come e (vedi gli esempi di seguito).
- Usa il markup per i tasti come ctrl e x per evidenziare la pressione di un tasto (vedi gli esempi di seguito).
- Includere screenshot quando necessario. Il metodo preferito per aggiungere screenshot di Zammad è crearli automaticamente utilizzando Cypress. Questo supporta la manutenibilità della documentazione poiché gli screenshot vengono rigenerati ogni volta che viene eseguita la pipeline di build. Si prega di notare che l'utilizzo di Cypress non fa parte di questa documentazione.
- Fornisci istruzioni passo passo con spiegazioni chiare.
- Usa esempi o scenari per illustrare i concetti.
- Includi immagini o diagrammi pertinenti quando necessario.
- Scrivi le abbreviazioni per esteso la prima volta che vengono usate, oppure includile nel glossario con un link.
- In caso di dubbio, allineati alla documentazione esistente.
Convenzioni
Lo stack della documentazione include controlli automatici (linting) per garantire la conformità alla guida allo stile e alle regole comuni per i file Markdown. Per verificare se le tue modifiche sono conformi, esegui pnpm lint. Alcuni dei problemi rilevati possono essere corretti automaticamente eseguendo pnpm lint:fix.
Il sistema di linting utilizzato ha alcune regole integrate che puoi trovare nel repository ufficiale. Alcune regole importanti e personalizzate sono menzionate di seguito.
- La lunghezza della riga di 120 caratteri nel file sorgente non deve essere superata per il testo standard. Assicurati di andare a capo prima di raggiungere questo limite. Questo non si applica a contenuti speciali come percorsi di screenshot e link lunghi.
- Non sono consentite più righe vuote consecutive.
- Le righe vuote prima e dopo le intestazioni e i blocchi di codice sono obbligatorie.
- Usa
```(backtick) per i blocchi di codice, seguiti da un tag lingua obbligatorio, ad esempiorubyosh. Se non si applica nessuna lingua, usaplain. - Usa
-per gli elenchi puntati (non ordinati) come questo. - Per distinguere facilmente tra grassetto e corsivo, usa
_intorno al testo per il corsivo e**per il grassetto. - Non sono consentite più intestazioni con lo stesso contenuto.
- Ogni documento deve avere esattamente un'intestazione
h1come titolo. - La risoluzione degli screenshot manuali a pagina intera per la visualizzazione mobile è di 400x867 pixel.
- La risoluzione degli screenshot manuali a pagina intera per la visualizzazione desktop è di 1920x1080 pixel.
In addition to pnpm lint, the repository uses Vale for prose linting. Vale checks for consistent brand name casing (e.g. GitHub, GitLab, Elasticsearch), flags discouraged terms, and enforces wordlist rules. It runs automatically on staged files when you commit and in CI alongside the Markdownlint job. To run it manually, use pnpm vale.
Esempi
Testo e interfaccia utente
| Type | Highlighting in documentation | Markdown syntax |
|---|---|---|
| Labeled buttons | Sign in | `Sign in` |
| Fields, labeled UI elements, menu items | Name | **Name** |
| Breadcrumb paths / navigation chains | Settings > Channels > Email | _Settings > Channels > Email_ |
| File and directory paths | /opt/zammad | `/opt/zammad` |
| Placeholder values for configuration | <your-fqdn> | `<your-fqdn>` |
| Placeholder values for API requests | {ticket id} | `{ticket id}` |
| Commandline config values, ports, keys | 9200 | `9200` |
| Keyboard shortcuts | x | [[x]] |
| Add button | ::+:: | |
| Delete button | ::x:: | |
| Action menu | ::a:: | |
| Copy to clipboard button |  | ::c:: |
Heading structure
Ogni file della documentazione deve includere esattamente un titolo al livello superiore (come # Titolo). I livelli inferiori devono contenere sempre almeno due sezioni.
Esempio:
# Titolo della pagina
## Sezione 1
### Sezione 1.1
### Sezione 1.2
## Sezione 2
Sezione con badge testo personalizzato
Il titolo di questa sezione utilizza un badge del tipo "avviso". Sono disponibili altri badge, vedere https://vitepress.dev/reference/default-theme-badge#usage.
Utilizzo:
Details
md
Testo/titolo per aggiungere un badge <Badge type="warning" text="testo personalizzato" />Riquadri personalizzati
INFO
Questo è un riquadro informativo.
Utilizzo:
Details
md
::: info
Questo è un riquadro informativo.
:::TIP
Questo è un suggerimento.
Utilizzo:
Details
md
::: tip
Questo è un riquadro suggerimento.
:::WARNING
Questo è un avviso.
Utilizzo:
Details
md
::: warning
Questo è un riquadro avviso.
:::DANGER
Questo è un avviso pericoloso.
Utilizzo:
Details
md
::: warning
Questo è un avviso pericoloso.
:::Details
Questo è un blocco dettagli.
Utilizzo:
md
::: details
Questo è il contenuto mostrato nello stato espanso.
:::Elenchi di definizioni
- First term tag1
- This is the definition of the first term.
- Second term tag1 tag1
- This is one definition of the second term.
- This is another definition of the second term.
Utilizzo:
Details
md
First term <Badge type="info" text="tag1" />
: This is the definition of the first term
with another line.Highlighting with boxes
Per evidenziare opzioni o varianti diverse, è possibile usare riquadri cliccabili.
La definizione del contenuto avviene tramite frontmatter, vedi il seguente esempio (rispecchia i riquadri sopra):
yml
features:
- icon: 🛠️
title: Semplice e minimale, sempre
details: Lorem ipsum...
link: https://zammad.com
linkText: Questo è un link
target: _blank
- icon:
src: /assets/logo.svg
title: Un'altra funzionalità interessante
details: Lorem ipsum...
link: https://zammad.com
- icon:
dark: /assets/logo-flat-dark.svg
light: /assets/logo-flat-light.svg
title: Un'altra funzionalità interessante
details: Lorem ipsum...
link: https://zammad.comPer posizionarlo nell'area del contenuto, inserisci semplicemente il riferimento <VPDocFeatures /> nel punto in cui deve essere renderizzato.
Theme specific images
Per destinare risorse immagine specifiche a un singolo tema, puoi assegnare la classe CSS .dark-only o .light-only all'immagine corrispondente:
md
{.dark-only}
{.light-only}
{.dark-only width=240} 