Piano documentazione utente Eurocoge¶

Stato: prototipo in corso¶

Data avvio riflessione: 2026-02-18 Data primo prototipo: 2026-02-19

Problema attuale¶

3 fonti di verita' che divergono: 1. Codice COBOL — sempre aggiornato, e' il software che gira 2. Documentazione tecnica in docs/dev/ — parziale ma affidabile (generata dal codice) 3. Documentazione utente su ClickUp — parziale, non allineata, migrata da Help&Manual

Il documento ClickUp e' stato reso "pubblico" per i clienti, ma ClickUp non e' uno strumento documentale: limiti di navigazione, ricerca, versioning.

Obiettivo¶

Produrre una documentazione utente completa, allineata al codice, accessibile ai clienti, e soprattutto mantenibile nel tempo.

Decisione: Markdown nel repo¶

La documentazione utente vive nel repository come file Markdown, nella cartella docs/.

Vantaggi¶

Vive nel repo → si aggiorna con il codice nello stesso commit
Markdown → leggibile ovunque, convertibile in qualsiasi formato
Pubblicabile come sito statico navigabile con ricerca e indice
Esportabile in PDF se necessario
Migrabile da ClickUp in modo incrementale

Capacita' del Markdown¶

Hyperlink: si', sia interni (tra pagine) che esterni
Immagini: si', con ![descrizione](percorso/immagine.png)
Tabelle, liste, code blocks, note/avvisi: tutto supportato
Stile grafico: applicato da MkDocs Material (colori, font, layout, logo, sidebar, ricerca)

Strumento di pubblicazione: MkDocs Material ✓¶

Decisione presa il 2026-02-19.

Cos'e': generatore di siti statici pensato per documentazione
Installazione: pipx install mkdocs-material --include-deps (sul Mac)
Configurazione: file mkdocs.yml nella root del progetto
Anteprima locale: mkdocs serve → http://127.0.0.1:8000
Generazione sito: mkdocs build → cartella site/
Nota: dopo aver aggiunto file nuovi, riavviare mkdocs serve

Installazione effettuata¶

Installato su MacBook (non sul server Linux) — comodo per anteprima nel browser
Versione: mkdocs 1.6.1, mkdocs-material 9.7.2
Installato via pipx (non pip) per compatibilita' con Python gestito da Homebrew
Dopo l'installazione: pipx ensurepath per aggiungere i comandi al PATH

Struttura della documentazione¶

Decisione presa il 2026-02-19: struttura ibrida menu + guide.

Due sezioni principali¶

Menu applicazione (docs/menu/): organizzata per menu del gestionale, suddivisa per sottomenu. L'utente trova la doc dove si aspetta nel software
Guide operative (docs/guide/): percorsi trasversali che attraversano piu' menu (es. "Come emettere una fattura")

Struttura cartelle¶

eurocoge/
├── mkdocs.yml                # Configurazione MkDocs
├── docs/                     # Documentazione utente
│   ├── index.md              # Home page
│   ├── img/                  # Screenshot e immagini
│   │   └── contabilita/      # Immagini per sezione contabilita'
│   ├── menu/                 # 1) MENU APPLICAZIONE
│   │   ├── contabilita/
│   │   │   ├── index.md
│   │   │   ├── archivi-tabelle/
│   │   │   │   └── clienti.md    ← primo prototipo
│   │   │   ├── prima-nota/
│   │   │   ├── documenti-iva/
│   │   │   ├── fatture-fornitori/
│   │   │   ├── centri-costo/
│   │   │   ├── clienti-partite-aperte/
│   │   │   ├── fornitori-partite-aperte/
│   │   │   ├── bilancio/
│   │   │   ├── clienti-potenziali/
│   │   │   ├── cespiti/
│   │   │   ├── coassicurazioni/
│   │   │   ├── soci/
│   │   │   └── stampe/
│   │   ├── magazzino/
│   │   ├── vendite/
│   │   ├── ordini/
│   │   ├── statistiche/
│   │   ├── crm/
│   │   ├── laboratorio-odontotecnico/
│   │   ├── assistenza-tecnica/
│   │   └── sistema/
│   ├── guide/                # 2) FLUSSI TRASVERSALI
│   └── import/               # Sorgenti ClickUp (non pubblicati)
├── docs/dev/                 # Documentazione tecnica (per sviluppatori)

Convenzioni di naming¶

Elemento	Convenzione	Esempio
File .md (menu)	Codice programma in minuscolo	`coge08c.md` (titolo nel documento: "Anagrafica Clienti")
File .md (guide)	Nome descrittivo	`commesse/index.md`, `commesse/chiusura.md`
Cartelle menu	Slug del sottomenu	`archivi-tabelle/`, `prima-nota/`
Immagini	`{funzione}-{contesto}.jpg`	`clienti-pag1-principale.jpg`
Cartelle immagini	Per sezione menu	`docs/img/contabilita/`
Titolo documento	Nome funzionale leggibile	`# Anagrafica Clienti`
Codice programma	Nell'intestazione del documento	`Programma: COGE08C`

Il naming per codice programma consente il collegamento diretto dall'applicazione (es. DT-coge08c.html).

Tracciabilita' programma → doc utente¶

La colonna "Doc utente" nel registro programmi (docs/dev/registro-programmi.md) mappa ogni programma alla sua pagina di documentazione utente. Va aggiornata quando si crea una nuova pagina.

Destinatari e approccio¶

Due lettori, un solo documento¶

I destinatari principali sono: - Operatore: usa il gestionale ogni giorno, ha bisogno di sapere cosa fare - Responsabile: deve capire le regole di business e la logica del sistema

Decisione: documento unico strutturato a livelli, non documenti separati per ruolo.

La struttura della pagina serve entrambi grazie alla progressione delle sezioni: - L'operatore legge "A cosa serve → Come si accede → Operativita'" e ha finito - Se qualcosa non funziona, va a "Messaggi di errore" - Il responsabile legge "A cosa serve → Regole di business" e capisce la logica

Nessuna duplicazione, un solo documento da mantenere.

Profondita', non separazione¶

La stessa informazione appare a due livelli di dettaglio nella stessa pagina.

Esempio sulla garanzia: - In Operativita': "Se il sistema trova una chiamata precedente con lo stesso codice, propone il collegamento in garanzia. Il flag va attivato manualmente." - In Regole di business: "La ricerca garanzia considera le chiamate degli ultimi 60 giorni con lo stesso codice chiamata cliente. I giorni garanzia sono determinati dal modello configurato per la combinazione tipo attivita' + cliente + brand + azienda. Il flag garanzia non si attiva automaticamente."

Template pagina utente¶

# Titolo funzione

## A cosa serve
[1-2 frasi per orientare l'utente — tutti]

## Come si accede
[Menu → Area → Sottomenu → Funzione — operatore]

## Prerequisiti
[Cosa deve essere configurato/preparato prima di usare questa funzione]

## Operativita'
[Passo-passo con riferimenti ai campi della maschera — operatore]
[Livello di dettaglio: cosa fare, non perche']

## Regole di business
[Logica del sistema, criteri di calcolo, soglie — responsabile]
[Livello di dettaglio: perche' il sistema si comporta cosi']

## Messaggi di errore
[Tabella: messaggio → causa → cosa fare — operatore]

## Vedi anche
[Link ad altre sezioni correlate — tutti]

Linee guida di stile¶

La documentazione deve funzionare come materiale di formazione per colleghi che poi formeranno i clienti. Queste linee guida si applicano a tutte le pagine, sia menu che guide operative:

Flussi operativi passo-passo: "prima fai questo, poi questo", con chiara sequenza delle azioni
Esempi concreti legati al contesto d'uso (es. "produzione di 500 croissant" per il settore alimentare)
Prerequisiti chiari: "prima di usare questa funzione, assicurarsi che..."
Trappole comuni e punti critici evidenziati con admonition (warning, note)
Linguaggio pratico, non tecnico: descrivere cosa vede l'operatore, non come funziona il codice

Processo di generazione¶

Per ogni pagina di documentazione utente:

1. Doc ClickUp (se disponibile)      → cosa c'era scritto per l'utente
2. Doc tecnica (docs/dev/flussi/)      → mappa dei sorgenti e struttura
3. Sorgenti COBOL (cbl/, cpy/)      → lettura diretta dal codice
         |
         v
   Claude analizza le 3 fonti:
   - Dal codice: campi reali, validazioni, messaggi di errore, regole
   - Dalla doc tecnica: architettura, file collegati, catene di chiamata
   - Da ClickUp: descrizioni utente-friendly, prassi operative
         |
         v
   Bozza doc utente (docs/)  →  Revisione Andrea  →  Pubblicazione

Nota: il codice COBOL e' la fonte di verita'. La doc tecnica serve come mappa per sapere quali sorgenti leggere. Il ClickUp e' solo un confronto per recuperare descrizioni e verificare completezza.

Colonna nel registro: "Doc tecnica" in docs/dev/registro-programmi.md mappa ogni programma alla sua documentazione tecnica.

Input da ClickUp¶

ClickUp e' una SPA: non e' possibile fare fetch diretto delle pagine
L'export in formato Markdown (.md) funziona e va messo in docs/import/
Le immagini ClickUp sono su server esterni: vanno scaricate manualmente (clic destro → salva) e messe in docs/img/
La cartella docs/import/ non viene pubblicata nel sito

Screenshot¶

Le pagine possono includere screenshot delle maschere del gestionale.

Cartella: docs/img/{sezione}/ (es. docs/img/contabilita/)
Formato: JPG (qualita' media 60%, larghezza default 800px)
Naming: {funzione}-{contesto}.jpg (es. clienti-pag1-principale.jpg)
Fonte: catturati dal gestionale, salvati con comando salva-img (vedi sotto)
Riferimento nel .md: ![Pagina Principale](../../../img/contabilita/clienti-pag1-principale.jpg)
Shortcut Mac: funzione salva-img in ~/.zshrc — richiede pngpaste (brew install pngpaste)

Primo prototipo¶

Data: 2026-02-19 Area pilota: Contabilita' → Archivi e Tabelle → Clienti (COGE08C) File generato: docs/menu/contabilita/archivi-tabelle/coge08c.md Stato: bozza generata, in attesa di revisione

Il prototipo ha validato: - Il template a 6 sezioni funziona - Il processo di generazione da 3 fonti produce documentazione completa - MkDocs Material genera un sito navigabile e leggibile - La struttura cartelle menu/sottomenu funziona

Decisioni ancora da prendere¶

[x] ~~Area pilota~~ → Contabilita' / Archivi e Tabelle / Clienti
[x] ~~Importare doc ClickUp o partire da zero?~~ → ClickUp come confronto, codice come fonte di verita'
[x] ~~Strumento di pubblicazione~~ → MkDocs Material (installato su Mac)
[x] ~~Screenshot~~ → si', in docs/img/, scaricati manualmente
[x] ~~Naming file .md~~ → nome funzionale (clienti.md), codice programma nell'intestazione
[x] ~~Struttura navigazione~~ → ibrida menu + guide, suddivisa per sottomenu
[x] ~~Tracciabilita' programma → doc~~ → colonna "Doc utente" nel registro programmi
[ ] Infrastruttura di pubblicazione (dove ospitare il sito generato per i clienti)
[ ] Logo e personalizzazione grafica del tema Material
[ ] Revisione del prototipo clienti e feedback