Skip to content

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 ​

AudienceCosa si aspetta
Ops / DevOpsProcedure, env, verifica, rollback, path compose/CI
SviluppatoriDocType, API, hook, path codice, ADR
Cliente tecnico / operatorePercorsi 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:

  1. Scopo — cosa risolve la pagina (2–4 frasi).
  2. Prerequisiti — accessi, tool, branch, env, permessi.
  3. Procedura — passi numerati con comandi verificabili e path reali.
  4. Verifica — comandi o check UI che dimostrano successo.
  5. 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 ​

StrumentoUsare quando
TabellaDocType/campi, env, ruoli, workflow CI, mapping protocollo
MermaidFlussi deploy, sequenze integrazione, ER semplificato, state machine
ADR (docs/architecture/adr/)Decisione architetturale con alternative e conseguenze
Codice inlineSolo snippet corti; path file per riferimenti lunghi

Cosa è vietato ​

  • Pagine che sono solo un indice di link senza spiegazione.
  • TBD, TODO, Coming soon come 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 .env reali.
  • Link orfani (file/sidebar senza pagina, o pagina non in sidebar se è pubblica).
  • Duplicare procedure lunghe in due posti: una fonte canonica + link breve.
ElementoConvenzione
File markdownkebab-case.md sotto la cartella tematica
H1Un solo H1 per pagina, allineato al titolo sidebar
H2/H3Sezioni della struttura obbligatoria o logiche
Link VitePressRelativi senza estensione .md: /architecture/overview, ../modules/machines
Path repoSempre 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:

  1. Aggiornare docs/.vitepress/config.mts (nav e/o sidebar).
  2. Se è un ingresso principale, aggiornare anche le features in docs/index.md.
  3. Eseguire npm run docs:build e 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:build OK.

Ez FactoryOS — MES per Ortobellina / OP Raggio di Sole · App Frappe v16 ez_factoryos