Stesura pagine 2

Introduzione

Questo manuale definisce le linee guida per scrivere e formattare correttamente i manuali di EagleArca.

L'obiettivo è garantire una documentazione uniforme, chiara e comprensibile.
Le seguenti regole sono valide per tutte le sezioni del manuale e devono essere seguite da chiunque scriva o editi una pagina di manualistica.

Contenuti

➡️Titolo

Il titolo della pagina deve essere esattamente come riportato nel file Excel “Alberatura manuali”.
Sono da evitare modifiche o parafrasi, il titolo deve corrispondere esattamente.

➡️Tag

I tag indicati nell'Excel sono obbligatori ed essenziali. Devono essere aggiunti e verificati prima della pubblicazione della pagina.

➡️Introduzione della pagina

Ogni pagina deve iniziare con un’introduzione breve, che spiega a cosa serve la sezione trattata. L’introduzione deve essere chiara, concisa e deve evitare ripetizioni.

➡️Callout info

I callout sono elementi informativi che devono essere usati per evidenziare informazioni chiave, come i moduli o permessi necessari.
Esempio:

Disponibile con il modulo nome-modulo attivo nel progetto

A volte può essere necessario inserire un avviso che non si qualifica come callout, ma come informazione extra.
Questi avvisi possono essere inseriti direttamente nel corpo della pagina. Vanno usati per chiarire condizioni particolari.
Esempio:

Le misure nella vista 3D funzionano solo se effettuate all'interno della nuvola di punti o della mash.

➡️Requisiti

I requisiti sono facoltativi e devono essere utilizzati solo quando necessari. Ogni pagina può includere un capitolo "Requisiti" che descrive le condizioni da soddisfare per eseguire l'azione descritta nella pagina.
Esempi:

“Devi aver ricevuto una mail di benvenuto con un link per il primo accesso.”

"Permesso: backoffice per creare e modificare le classi oggetto Global List.”

➡️Corpo centrale

Il corpo centrale deve contenere una descrizione dettagliata della funzionalità o delle azioni che si possono eseguire.

Se esiste un ordine preciso di azioni, inserire il capitolo “Passaggi” e organizzare le azioni in un elenco numerato con una spiegazione chiara per ogni passo.

Quando i passaggi non sono necessari, descrivi semplicemente le funzionalità o le caratteristiche della sezione.

➡️Suggerimenti utili

Gli suggerimenti utili sono consigli facoltativi che migliorano l’esperienza dell'utente o forniscono informazioni aggiuntive.

L’uso di suggerimenti è facoltativo, ma aiuta a dare valore aggiunto alla sezione.

➡️Collegamenti

I collegamenti sono essenziali e devono essere sempre inclusi.

Vanno utilizzati per rimandare ad altre pagine correlate alla sezione. Le pagine da collegare possono far parte dello stesso libro o di altri.

➡️Problemi comuni

I problemi comuni non sono obbligatori, ma sono molto utili se ci sono errori o casi frequenti che gli utenti possono incontrare. Quando vengono aggiunti, devono essere presentati in una tabella Problema/Soluzione con uno stile "stile pieno" e una larghezza del 100%.

➡️Ultimo aggiornamento

La data di ultimo aggiornamento è obbligatoria e va sempre inclusa alla fine di ogni pagina. Deve corrispondere all'ultima modifica sostanziale e deve essere formattata in corsivo.

Regole di linguaggio

Impersonale o rivolta direttamente all'utente: Usa forme come puoi, seleziona, clicca.

Struttura delle frasi: Obiettivo → Azione: Per consentire all'utente di ritrovare più rapidamente quello che cerca. Esempio: Per nascondere la vista, clicca sul bottone Nascondi.

Frasi brevi e dirette: Evita formulazioni colloquiali e usa un linguaggio semplice e chiaro.

Lessico uniforme: Usa sempre lo stesso termine per gli stessi concetti, per esempio pannello, vista, classe oggetto, chip.

Formattazione

Una corretta formattazione è essenziale per garantire una lettura chiara e coerente del manuale. Di seguito sono descritte le regole di formattazione da seguire.

Evidenziazione degli elementi dell’interfaccia:
- Bottoni: Quando parli di bottoni, scrivi sempre il nome del bottone in grassetto: clicca sul bottone Aggiungi.
- Chip: Scrivi sempre i nomi delle chip in grassetto quando vanno usate in azione.
- Moduli/permessi: Usa sempre il tag <code>…</code> per evidenziare moduli o permessi.

Elenchi puntati e numerati

Gli elenchi devono essere organizzati in modo chiaro e ordinato. Quando hai elenchi puntati o numerati, tra un punto ed un altro va aggiunto uno spazio con Shift + Invio.
Esempio:
- Titolo 1
  Descrizione del punto.
- Titolo 1
  Descrizione del punto.

Suggerimenti utili
La formattazione per i suggerimenti deve essere:
- 💡 Titolo in grassetto
  Spiegazione estesa.

Tabelle e loro formattazione
Formato delle tabelle:
- Le tabelle devono essere formattate con stile pieno e larghezza 100%.
- La prima riga deve contenere i titoli delle colonne (ad esempio, Problema e Soluzione).
- Esempio di tabella:
  
  Problema Soluzione
  Non vedo una classe oggetto in mappa Se si tratta di una classe di tipo form, è visibile solo nel pannello Inventory.

Problema	Soluzione
Non vedo una classe oggetto in mappa	Se si tratta di una classe di tipo form, è visibile solo nel pannello Inventory.

Copiare per ChatGPT

Se devi aprire una nuova chat con ChatGPT, copia e incolla questa sezione per trasferire lo stile:

Titoli sezioni: ###

Linguaggio:
- Chiarezza: frasi brevi, comprensibili al primo colpo.
- Professionale ma accessibile: linguaggio naturale, non colloquiale o rigido.
- Impersionale o diretto all’utente: usa “puoi”, “seleziona”, “clicca”.
- Descrittivo e guidato: spiega le azioni passo passo.
- Coerente: stesso lessico per interfaccia (bottone, chip, vista, classe oggetto, toolbar, searchbar).
- Orientato all’azione: chiaro cosa fare e cosa succede dopo l’azione.
- Presente indicativo: evitare futuro e condizionali.
- Esempio corretto: “Per eliminare un oggetto, seleziona l’oggetto in mappa e clicca sul bottone Elimina.” Esempi da evitare: “L’utente deve andare sul bottone elimina…” “Puoi provare a cliccare sul bottone elimina…”

Callout info:
- Moduli: <p class="callout info">Disponibile con il modulo <code>nome-modulo</code> attivo nel progetto.</p>
- Backoffice + moduli: <p class="callout info">Disponibile per <code>backoffice</code> con il modulo <code>nome-modulo</code> attivo nel progetto.</p>
- Didascalie avviso: testo breve inserito nel corpo centrale, non formattato come callout.

Requisiti: capitolo dedicato, solo se utili.

Passaggi: elenco numerato (1., 2., 3.) con frase completa per ogni step.

Suggerimenti utili, linguaggio al presente, diretto e chiaro. Es. struttura:
💡 Titolo in grassetto
Spiegazione estesa

Collegamenti: elenco puntato con link alle pagine correlate.

Tabelle Problemi comuni: HTML <table> con id univoco, stile pieno e larghezza 100%.

Ultimo aggiornamento in fondo, in corsivo:
***Ultimo aggiornamento:** 24 settembre 2025*

Check prima della pubblicazione ufficiale

◽Tag presenti e conformi all’Excel.
◽Corpo centrale strutturato in sezioni ordinate.
◽Requisiti aggiunti se necessari.
◽Suggerimenti utili formattati correttamente.
◽Collegamenti presenti e pertinenti.
◽Problemi comuni se utili e tabella formattata correttamente.
◽Istruzioni chiare e comprensibili.
◽Data di ultimo aggiornamento corretta.