Policy di documentazione

La documentazione è un tassello fondante, non un'attività di chiusura. Codice e doc cambiano nello stesso commit. Doc disallineata è trattata come un bug.

I quattro tipi di documento

Tipo	Risponde a	Dove	Quando si scrive
Scheda pipeline	"Cosa fa questa pipeline, da dove a dove, con quali regole?"	docs/pipelines/<nome>.md	Insieme alla pipeline
ADR (Architecture Decision Record)	"Perché abbiamo scelto X invece di Y?"	docs/architecture/adr/	Quando prendi una decisione strutturale
Runbook	"Come si esegue / ripristina / fa backfill in produzione?"	docs/runbooks/	Prima del primo deploy in produzione
JSDoc nel codice	"Perché questa funzione esiste e come si usa?"	Inline, sopra le API pubbliche	Mentre scrivi il codice

Regole

1. Stesso commit. Se cambi un comportamento, aggiorni la doc che lo descrive nello stesso atto.
2. Una fonte di verità. Un fatto vive in un solo posto; gli altri documenti lo linkano. Niente copia-incolla.
3. Il perché batte il cosa. Il codice mostra il cosa; la doc spiega il perché e i trade-off.
4. Esempi eseguibili. Dove possibile, gli esempi in doc derivano da test reali (così non marciscono).
5. Manutenzione attiva. Le PR che toccano una pipeline devono toccarne la scheda.
6. Doc sync a lavoro finito. Quando una funzionalità viene aggiunta, modificata o rimossa, a implementazione completata si esegue il doc sync (agente doc-syncer o /doc-sync) e si chiudono tutte le derive prima della PR. Le rimozioni contano quanto le aggiunte: niente schede orfane, niente riferimenti a nomi che non esistono più.

Scheda pipeline — contenuto minimo

Ogni docs/pipelines/<nome>.md contiene:

• Scopo e dominio dati.
• Sorgente(i) e Sink(i): sistema, schema, chiave naturale.
• Trasformazioni e regole di business (con riferimento al codice).
• Schedulazione e cadenza (daily/hourly/on-demand).
• Parametri (ctx.params) e variabili d'ambiente richieste.
• Idempotenza: come è garantita.
• Gestione errori: cosa finisce nel dead-letter e come si recupera.
• Owner e link al runbook.

Vedi il template: docs/pipelines/README.md.

Il sito di documentazione

I documenti di docs/ sono anche un sito statico, generato con VitePress (ADR-0043). Il markdown resta la fonte: il sito non ne contiene copie, quindi aggiornare un documento aggiorna il sito.

pnpm run docs:dev         # variante pubblica in locale, con ricaricamento a caldo
pnpm run docs:dev:app     # variante dell'app, con le schede pipeline
pnpm run docs:build       # variante pubblica in docs/.vitepress/dist/
pnpm run docs:build:app   # variante dell'app in docs/.vitepress/dist-app/
pnpm run docs:preview     # serve la build pubblica appena fatta

Il gate (pnpm run check, e la CI) builda entrambe le varianti.

• Dove si legge. Nell'app desktop, pulsante Guida (ADR-0044): la build della UI (pnpm run docs:bundle in noeva-etl-ui) include il sito così com'è su questo checkout, quindi un documento cambiato arriva nell'app con la release successiva. La variante pubblica si legge anche da browser, su Cloudflare Workers, ripubblicata a ogni push su main (ADR-0045, runbook). In locale, pnpm run docs:dev.

• Cosa si pubblica. Tutto docs/ tranne plans/, agents/ e runbooks/template.md. I link verso file fuori dal sito (codice, CLAUDE.md, i piani) puntano al file su GitHub; dentro l'app si aprono nel browser di sistema.

• Due varianti: app e public (ADR-0044). Ogni cliente ha le sue pipeline, quindi ciò che parla di un cliente esiste solo nella variante app, quella dentro l'app desktop. La variante public — il default, per un hosting esterno — esclude i percorsi in APP_ONLY (docs/.vitepress/lib/docs-target.ts: docs/pipelines/ e i runbook delle pipeline di un cliente), e i link verso di essi diventano testo semplice.

• Scrivere qualcosa di specifico di un cliente. Una scheda pipeline va in docs/pipelines/, ed è già esclusa dalla variante pubblica; un altro documento dedicato a un cliente, come un runbook, si aggiunge ad APP_ONLY. Un passaggio che nomina un cliente dentro un documento pubblico — "Chi lo usa", "Primo utilizzo" — va in un blocco che la variante pubblica toglie:

  ::: solo-app
  Primo utilizzo: `pipeline-del-cliente`.
  :::

  Negli esempi di codice si usano nomi neutri. Per controllare che non sfugga nulla, cercare il nome del cliente nella build pubblica (docs/.vitepress/dist/).

• Dove va una pagina nuova. Le schede di connettori e pipeline, i runbook e gli ADR entrano nella sidebar da soli (le schede pipeline solo nella variante app), col titolo preso dal loro H1. Una pagina di percorso, pensata per chi usa o crea processi, va in docs/guide/ e si aggiunge alla sidebar in docs/.vitepress/config.ts.

• Contenuti interattivi. I componenti leggono i dati dai documenti a ogni build: la tabella dei tipi di nodo in GUIDA_SVILUPPO.md, la mappa Talend nel README.md, gli ADR, il frontmatter di comandi, subagent e skill in .claude/. Se una di quelle tabelle cambia intestazioni la build fallisce e dice quale: si aggiorna il loader, non si ricopia il dato.

• Un vincolo di scrittura. VitePress compila il markdown come template Vue, quindi un tag HTML sconosciuto fuori da un blocco di codice rompe la build. I segnaposti vanno sempre fra backtick (`<nome>`); un segnaposto finito a inizio riga dopo un a capo è gestito dal sito.

• Il contratto con l'app. Tema, link esterni e il segnale di sito pronto passano da postMessage: docs/.vitepress/lib/embed-protocol.ts qui, src/lib/docs-embed.ts in noeva-etl-ui. Chi cambia una metà cambia l'altra.

ADR — formato

Numerati progressivamente (NNNN-titolo.md), stato Proposta | Accettata | Sostituita. Template e indice: docs/architecture/adr/README.md.