Linea guida scrittura documentazione
Scopo
Definire come scrivere e mantenere la documentazione pubblica VitePress di Ez FactoryOS (docs/ → docs.factoryos.ezbit.it), in modo che ogni pagina sia operativa e autocontenuta.
Regola Cursor correlata: .cursor/rules/docs-writing.mdc (si attiva su docs/**/*.md). Regola inventario moduli/ADR: .cursor/rules/documentation.mdc.
Audience
| Audience | Cosa si aspetta |
|---|---|
| Ops / DevOps | Procedure, env, verifica, rollback, path compose/CI |
| Sviluppatori | DocType, API, hook, path codice, ADR |
| Cliente tecnico / operatore | Percorsi Desk click-passo, convenzioni campi, export CSV |
Tono
- Tecnico e operativo: imperativi, elenchi numerati, tabelle.
- Non narrativo: niente storytelling, marketing o "come abbiamo deciso di…".
- Accuratezza rispetto al codice: documentare solo funzioni presenti in
apps/ez_factoryos/deploy/. Vietato descrivere sviluppi futuri, roadmap o "prossimi passi". - Lingua: italiano (docs già in IT). Termini tecnici in inglese se sono nomi reali (DocType, branch, env).
Struttura obbligatoria per pagina operativa
Ogni pagina di setup, infrastruttura, operazioni o procedura deve avere, nell'ordine:
- Scopo — cosa risolve la pagina (2–4 frasi).
- Prerequisiti — accessi, tool, branch, env, permessi.
- Procedura — passi numerati con comandi verificabili e path reali.
- Verifica — comandi o check UI che dimostrano successo.
- Rollback / Troubleshooting — come tornare indietro o diagnosticare i fallimenti tipici.
Pagine di overview (architettura, modello dati, home moduli):
- Contesto e decisioni (o link ADR).
- Diagramma Mermaid se chiarisce un flusso.
- Tabella dei contenuti presenti nel codice.
- Link a procedure dettagliate (non sostituire il contenuto con soli link).
Quando usare tabelle, Mermaid, ADR
| Strumento | Usare quando |
|---|---|
| Tabella | DocType/campi, env, ruoli, workflow CI, mapping protocollo |
| Mermaid | Flussi deploy, sequenze integrazione, ER semplificato, state machine |
ADR (docs/architecture/adr/) | Decisione architetturale con alternative e conseguenze |
| Codice inline | Solo snippet corti; path file per riferimenti lunghi |
Cosa è vietato
- Pagine che sono solo un indice di link senza spiegazione.
TBD,TODO,Coming sooncome contenuto.- Riferimenti a sviluppi futuri, roadmap, fasi non implementate, "prossimi passi", stati Pianificato/Previsto.
- Feature inventate o non presenti in
apps/ez_factoryos/deploy/. - Secret, password, token, chiavi API, dump
.envreali. - Link orfani (file/sidebar senza pagina, o pagina non in sidebar se è pubblica).
- Duplicare procedure lunghe in due posti: una fonte canonica + link breve.
Convenzioni naming e link
| Elemento | Convenzione |
|---|---|
| File markdown | kebab-case.md sotto la cartella tematica |
| H1 | Un solo H1 per pagina, allineato al titolo sidebar |
| H2/H3 | Sezioni della struttura obbligatoria o logiche |
| Link VitePress | Relativi senza estensione .md: /architecture/overview, ../modules/machines |
| Path repo | Sempre dal root: apps/ez_factoryos/..., deploy/compose/... |
Requisiti per tipologia di contenuto
Modulo / DocType
- Elenco DocType con naming series e campi chiave.
- Ruoli e permessi rilevanti.
- Flusso UI o API esistente con percorso Desk click-passo.
Integrazione
- Endpoint, header auth, variabili env (solo nomi).
- Sequenza Mermaid Desk ↔ gateway ↔ macchina.
- Riferimento ADR e path
deploy//integrations/. - Default sicuri (es.
OT_WRITES_ENABLED=0).
Infrastruttura
- Compose/path Coolify, servizi, porte (pubbliche vs interne).
- Ambienti
development/staging/production. - Nessuna porta OT pubblica; Coolify gestisce proxy HTTPS.
Operazioni
- Trigger (branch/PR/workflow).
- Procedura automatica e, se utile, manuale.
- Verifica health + rollback linkato.
Guida d'uso (cartella uso/)
- Percorso Desk completo (Awesome Bar → List → Form → Salva).
- Ruolo minimo richiesto per ogni azione.
- Convenzioni di compilazione campi ed export CSV.
- Riferimento ai concetti Frappe in Fondamenti.
Aggiornare nav e sidebar
Dopo aver creato o rinominato una pagina pubblica:
- Aggiornare
docs/.vitepress/config.mts(nave/osidebar). - Se è un ingresso principale, aggiornare anche le
featuresindocs/index.md. - Eseguire
npm run docs:builde correggere link morti evidenti.
Checklist PR docs
- [ ] Pagina autocontenuta (non solo indice).
- [ ] Solo funzioni presenti nel codice, nessun riferimento futuro.
- [ ] Nessun secret.
- [ ] Path e comandi reali.
- [ ] Sidebar/nav aggiornati.
- [ ]
npm run docs:buildOK.
