# Come si scrive un manuale "vero" `nuovo.mjs` produce un manuale completo ma **meccanico**: descrive cosa c'è in ogni schermata. Un manuale utile spiega invece come si lavora, in che ordine, con quali vincoli e perché. Questa è la procedura per arrivarci; i manuali di `rda` e `hq` sono gli esempi di riferimento. Il presupposto è che gli screenshot ci siano già (`capture.mjs`) e che si sia generato il dossier: ```bash node dossier.mjs /opt/gts//doc/manuale # -> dossier.md ``` Il dossier raccoglie dai sorgenti il materiale d'indagine: mappa del menu, campi per schermata, messaggi di validazione, legende dei codici, permessi con i file che li usano, azioni dei `*_cmd.php` con le transizioni di stato, integrazioni esterne. È materiale grezzo: si legge e si riscrive, non si copia. ## L'ordine dei capitoli Vale per tutte le app del framework; si saltano le sezioni che non si applicano. 1. **Introduzione** — a cosa serve l'applicazione in due paragrafi, glossario dei termini di dominio (uno per riga, spiegati come a un neoassunto), e una tabella "chi fa cosa" con i ruoli reali. 2. **Accesso** — login, portale, home, struttura del menu. È quasi identico per tutte le app: si può riusare quello di `rda`/`hq` cambiando i nomi. 3. **Consultazione** — la schermata di ricerca: ogni filtro spiegato uno per uno, le colonne dell'elenco, la legenda delle icone di riga, la legenda degli stati. Fonti: `hb_frow` della pagina, `arrHdi`/`hb_th` del `*_data.php`, gli array di legenda del dossier. 4. **Creazione e modifica** — la maschera blocco per blocco, i campi obbligatori **con le condizioni in cui lo diventano** (dai messaggi di validazione del dossier: sono la verità su cosa l'utente incontra), poi righe, note, allegati, stampa. 5. **Il flusso** — se l'app ha un ciclo di autorizzazione o di stato: chi fa cosa, in che ordine, cosa cambia ad ogni passo. Fonti: le azioni e le transizioni di stato del dossier. Va scritto dal punto di vista di chi preme il pulsante, non della tabella che cambia valore. 6. **Integrazioni** — invii verso altri gestionali, email automatiche, esportazioni: quando succedono, cosa producono, cosa fare se non succedono. 7. **Amministrazione** — le schermate di configurazione, con l'effetto pratico di ciascuna e chi dovrebbe toccarle. 8. **Appendici** — diagramma del ciclo di vita (SVG inline), tabella dei permessi con l'effetto di ognuno in italiano, notifiche automatiche. 9. **Procedure ricorrenti** (facoltativo ma prezioso) — i tre o quattro compiti che l'utente svolge davvero, in passi numerati, e una tabella "sintomo → dove guardare" per l'assistenza. È il capitolo che gli utenti leggono per primo. ## Regole di stesura - **Non inventare.** Ogni affermazione deve poggiare su codice letto. Dove il comportamento non è verificabile senza eseguire un'azione che modifica dati, descriverlo con prudenza invece di dedurlo. - **Le funzioni riservate vanno segnalate** con il permesso che le abilita: chi legge deve capire perché non vede un pulsante che il manuale mostra. - **Le figure si richiamano dal testo** e hanno didascalie che dicono cosa guardare, non che ripetono il titolo della schermata. - **Italiano piano**, frasi brevi, niente gergo tecnico dove esiste la parola comune (l'utente non sa cosa sia una `tablesorter`). - **I riquadri servono a due cose**: `nota` per le informazioni che evitano un malinteso, `attenzione` per le operazioni irreversibili. ## Quanto costa Con il dossier davanti, un'app media (una ventina di schermate) richiede una o due ore di stesura. Senza, la sola indagine sul codice ne richiede altrettante. ## Alla fine ```bash node topdf.mjs /opt/gts//doc/manuale ``` e un controllo di merito: riaprire due o tre schermate reali e verificare che i filtri, i pulsanti e le etichette citati nel testo esistano davvero con quel nome.