Tono e voce
Scrivi in uno stile tecnico, diretto al punto e conciso pur rimanendo accessibile. Privilegiare la chiarezza rispetto alla formalità.- Usa la voce attiva e la seconda persona (“tu”)
- Mantieni le frasi brevi: un’idea per frase
- Guida con l’obiettivo, quindi fornisci istruzioni
- Evita parole di riempimento non necessarie
- Nessuna copertura: sii fiducioso e diretto
- Nessun linguaggio di marketing: i documenti informano, non vendono
Attributi vocali
La voce della documentazione di Primo è sempre chiara, sicura, strutturata, orientata all’azione e professionale.| Attributo | Significa | NON significa |
|---|---|---|
| Cancella | Linguaggio semplice, un’idea per frase, nessuna ambiguità | Stupito o condiscendente |
| Fiducioso | Dichiarazioni dirette, nessuna copertura o scusa | Arrogante o invadente |
| Strutturato | Organizzato, scansionabile, logico | Rigido o robotico |
| Orientato all’azione | Guida l’utente verso le operazioni successive | Comandante o aggressivo |
| Professionista | Rispetta le competenze IT, utilizza la terminologia corretta | Pieno di gergo aziendale |
Impostazioni del tono
Gli articoli del Centro assistenza utilizzano formalità media, energia media e profondità tecnica elevata. Scrivi in modo professionale ma colloquiale, a un ritmo costante e utilizza liberamente la terminologia tecnica: i lettori sono professionisti IT.Convenzioni linguistiche
Terminologia
Utilizzare sempre i termini esatti del glossario. Non sostituire mai i termini del glossario con sinonimi.| Utilizzare | Evitare |
|---|---|
| Sistema HR | HRIS |
| il cruscotto | in Primo, in Primo |
| gestione dei dispositivi | MDM (al primo utilizzo, precisare) |
| dispositivo | macchina, calcolatore |
| iscriversi | registrarsi, aggiungere |
| Distribuzione zero-touch | configurazione automatica |
| onboarding/offboarding | alternative ad hoc |
Riferimenti di prodotto
Ridurre al minimo le menzioni di “in Primo” o “a Primo”. Includere il nome del prodotto solo quando:- Distinguere Primo da un altro sistema
- Prima menzione in un documento
- Senza di essa il contesto non sarebbe chiaro
Preferito: “Vai a Impostazioni” Evita: “Importa dipendenti in Primo”
Preferisco: “Importa dipendenti”
Acronimi
Scrivi gli acronimi al primo utilizzo, seguiti dall’abbreviazione tra parentesi. Utilizzare l’abbreviazione per le menzioni successive. Esempio: Gestione dispositivi mobili (MDM) consente la configurazione remota. I criteri MDM controllano le impostazioni del dispositivo.Convenzioni di stile
Intestazioni
- Utilizza la frase “Configura il tuo account” e non “Configura il tuo account”
- Utilizza verbi imperativi: “Configura SSO” e non “Configurazione SSO”
- Mantieni i titoli concisi e orientati all’azione
| Evitare | Preferisco |
|---|---|
| Configurazione delle impostazioni | Configura le impostazioni |
| Gestione dei dispositivi dei dipendenti | Gestisci i dispositivi |
| Comprendere zero-touch | Comprendere zero-touch |
| Importazione tramite CSV | Importa tramite CSV |
Formattazione
- Grassetto per gli elementi dell’interfaccia utente: fai clic su Impostazioni > Integrazioni
- Fai attenzione ai
**vaganti: indicatori in grassetto che non erano chiusi correttamente o che perdevano da un intervallo precedente. Una linea dovrebbe sempre avere un numero pari di contrassegni**. Modelli comuni da catturare:***word**(*extra iniziale) →**word****word **other**(marcatore aperto annidato) →**word other**
Code formattingper:- Nomi file:
config.json - Comandi:
mint dev - Percorsi:
/api/employees - Riferimenti al codice:
deviceId
- Nomi file:
- Utilizza
<Steps>per passaggi sequenziali: preferisci questo agli elenchi numerati ogni volta che i passaggi seguono un ordine definito - Negli attributi
<Step title="...">, non utilizzare la formattazione markdown: il grassetto (**) e i collegamenti ([text](url)) vengono visualizzati come caratteri letterali negli attributi JSX. Testo semplice solo nei titoli; utilizzare il corpo del passaggio per contenuti avanzati, se necessario - Utilizza gli elenchi puntati per gli elementi non sequenziali
Struttura dell’articolo
Segui uno schema coerente tra gli articoli:- Titolo — Verbo imperativo + oggetto (ad esempio, “Connetti il tuo sistema HR”)
- Descrizione: riepilogo di una frase di ciò che il lettore realizzerà
- Prerequisiti: elenca i requisiti prima di iniziare (se applicabile)
- Passi: istruzioni numerate con azioni chiare
- Passaggi successivi: collegamento al contenuto correlato (se applicabile)
Gruppi di carte
Utilizza<CardGroup> per visualizzare i collegamenti correlati come schede visive. Segui queste linee guida:
- Maximum 3 cards per row — Use
cols={3}or fewer for readability - Mantieni sincronizzata la copia delle carte: i titoli e le descrizioni delle carte devono corrispondere alla parte iniziale dell’articolo a cui si fa riferimento
- Utilizza le schede per le raccolte: ideale per le pagine di panoramica che collegano a contenuti correlati
Riferimento rapido
| Elemento | Convenzione | Esempio |
|---|---|---|
| Intestazioni | Caso della frase, imperativo | ”Configura crittografia disco” |
| Elementi dell’interfaccia utente | Grassetto | Fai clic su Salva |
| Codice/comandi | Backtick | Esegui mint dev |
| Nome del prodotto | Ridurre al minimo l’utilizzo | Omettere “in Primo” quando ovvio |
| Acronimi | Spiega il primo utilizzo | ”Sistema HR” e non “HRIS” |
| Card groups | Max 3 columns, synced copy | <CardGroup cols={3}> |
| Passaggi sequenziali | Utilizzare <Steps>@@I18N_SEG_117@@<Steps><Step title="..."> |