Stesura pagine 2

Introduzione

QuestoQuesta manualepagina definisce le linee guida percome 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.manuale DEPA.

È rivolta a chi crea, aggiorna o mantiene la documentazione.

L’obiettivo è garantire pagine:

coerenti tra loro

orientate all’obiettivo

chiare e sintetiche

facili da mantenere nel tempo

Le regole descritte in questa pagina devono essere sempre seguite quando si crea o modifica una pagina di manuale.

---

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 corrisponderedescrivere esattamente.l’obiettivo che la pagina permette di raggiungere, non la funzionalità in senso astratto.

➡️Tag

I tag indicati nell'Excel sono obbligatori ed essenziali.

Devono

Prima esseredella aggiuntipubblicazione:

verifica che tutti i tag siano presenti

assicurati che siano coerenti con il contenuto

I tag servono per organizzazione, ricerca e verificatimanutenzione primadel della pubblicazione della pagina.manuale.

➡️Introduzione della pagina

Ogni pagina deve iniziare con un’una introduzione breve,breve che(2–3 spiegafrasi).
L’introduzione deve:

spiegare a cosa serve la sezionepagina

trattata. L’introduzione deve

chiarire esserein chiara,quale concisacontesto viene usata

evitare descrizioni tecniche o storiche

Esempio corretto:
Questa pagina spiega come creare e deveconfigurare evitareuna ripetizioni.Classe Oggetto per definire struttura, attributi e stile degli oggetti nel progetto.

➡️Callout info

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

Disponibile con il modulo nome-modulo  attivo nel progettoprogetto.

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.

Non usare i callout per:

suggerimenti

spiegazioni operative

➡️Requisiti

Il capitolo Requisiti è facoltativo.  Inseriscilo solo se:

senza quei requisiti l’azione non è eseguibile

il requisito non è già evidente dall’interfaccia

I requisiti sono facoltativi e devono essere utilizzaticoncreti soloe quandoverificabili.

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.eseguire e deve spiegare come raggiungere uno o più obiettivi.

Ogni sezione deve seguire questo schema:

Obiettivo → Azioni necessarie

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

QuandoEsempio:

i

1. passaggiSeleziona uno o più oggetti.

2. Clicca sul bottone Sposta nella toolbar.

3. Afferra e sposta liberamente l'oggetto; è supportato lo snap con altri oggetti sulla mappa.

4. Clicca Conferma per salvare la nuova posizione (è disabilitato se non sonoc'è necessari,stato spostamento). Clicca Annulla per ripristinare la posizione originale.

Se non esiste un ordine rigido, descrivi semplicemente le funzionalitàazioni oin leforma caratteristichediscorsiva dellaorientata sezione.all’obiettivo.

➡️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.

I Suggerimenti utili sono facoltativi. Usali per:

scorciatoie

buone pratiche

comportamenti consigliati

Non devono introdurre nuove funzionalità.

➡️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.

I collegamenti alle altre pagine possono essere inseriti anche nel corpo del testo. In questo caso non vanno ripetuti nella sezione Collegamenti.

➡️Problemi comuni

ILa sezione problemiProblemi comuni nonè sono obbligatori,facoltativa ma sonofortemente moltoconsigliata utiliquando:

se

ci sono

esistono errori ofrequenti

casi frequenti che

l’interfaccia glinon utentirende possonoimmediata incontrare.la Quandocausa vengonodel aggiunti,problema

devono

Deve essere presentatipresentata in unacome tabella Problema/Problema / Soluzione, concon:

uno

• stile "stilepieno

  pieno"

e una

larghezza del100%

100%.

➡️Ultimo aggiornamento

LaOgni pagina deve terminare con la data di ultimo aggiornamento è obbligatoria e va sempre inclusa alla fine di ogni pagina. Deve corrispondere all'dell’ultima modifica sostanzialesostanziale, e deve essere formattata in corsivo.

corsivo con formato uniforme.

Serve per capire se la pagina è affidabile rispetto allo stato del prodotto.

---

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.
    
    

• ElenchiSpaziatura tra 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 12
    Descrizione del punto.
    
    

Elenchi numerati
Gli elenchi numerati devono essere creati manualmente.

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.

 

---

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 scritto a mano, non formattato automaticamente (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 conformicoerenti all’Excel.al contenuto.
◽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.