Table of Contents

Contribuire e correggere la documentazione

Questa documentazione e' viva: quando trovi un'imprecisione, un link rotto o un fatto ormai superato, correggilo. Non serve essere l'autore originale di una pagina per modificarla.

Ci sono due percorsi, a seconda di quanto sei a tuo agio con il repository.

Percorso Quando usarlo Sforzo
Issue (segnalazione) Hai notato un errore ma non hai tempo/voglia di scrivere la correzione. Basso
Pull Request (correzione) Sai gia' cosa scrivere e vuoi proporre il testo corretto. Medio

In fondo a ogni pagina del portale trovi i pulsanti ✏️ Modifica su GitHub, 🐛 Segnala un errore e 📄 Come contribuire: sono le scorciatoie ai due percorsi.

Important

Repository interno. Non rendere pubblico il repo, non pubblicare il portale su host raggiungibili da Internet e non incollare segreti (credenziali, connection string) nelle pagine, nelle issue o nelle PR.

Prima di tutto: cosa modifichi

La sorgente unica di verita' e' la cartella docs/ (Markdown). Non modificare docs-site/content/: e' una copia rigenerata a ogni build (rsync da docs/) e le modifiche andrebbero perse.

Ogni file .html del portale corrisponde a un .md sotto docs/:

portale:  .../content/05-databases/index.html
sorgente: docs/05-databases/index.md

Il pulsante ✏️ Modifica su GitHub su ogni pagina calcola gia' questo percorso e ti porta sul file giusto.

Percorso 1 - Segnalare un errore (issue)

  1. Dalla pagina imprecisa, clicca 🐛 Segnala un errore (oppure apri una issue su GitHub con l'etichetta documentazione).
  2. La issue arriva precompilata con la pagina e l'URL: descrivi cosa e' sbagliato e, se lo sai, qual e' il dato corretto e dove l'hai verificato (file path:riga, tabella, procedura).
  3. Un manutentore applica la correzione e chiude la issue citandola nel commit.

Le segnalazioni sono il modo piu' veloce per non perdere un'imprecisione anche quando non puoi correggerla subito.

Percorso 2 - Proporre la correzione (Pull Request)

Prerequisiti: accesso al repo GitHub e (per ricostruire il portale) docfx installato - vedi Guide per sviluppatori.

git clone --recurse-submodules https://github.com/DescorAI/infocad-documentation.git
cd infocad-documentation
git checkout -b docs/correzione-<argomento>

# modifica i file sotto docs/ ...

docs-site/scripts/build.sh       # ricostruisci (atteso: 0 error)
docs-site/scripts/validate.sh    # link locali (atteso: 0 link rotti)

git add docs/
git commit -m "docs: correggi <cosa> in <pagina>"
git push origin docs/correzione-<argomento>
# apri la Pull Request su GitHub

Nella descrizione della PR indica cosa hai cambiato e su quale evidenza ti sei basato (vedi sotto).

Regole di contenuto (importante)

Questa non e' documentazione a impressioni: e' evidence-backed. Rispetta queste regole, altrimenti la correzione rischia di introdurre affermazioni non verificabili.

  1. Classifica ogni affermazione non banale con uno di questi marcatori, coerentemente con il resto del portale: VERIFIED (visto nel codice/DB), SUPPORTED (indizi forti), INFERRED (deduzione), UNKNOWN (non determinabile), CONFLICTING (fonti in contrasto). Non promuovere a VERIFIED cio' che e' solo plausibile.
  2. Cita la fonte. Per il codice usa il formato cliccabile file:riga (es. Business/Start.vb:212); per il DB indica schema/tabella/procedura.
  3. Database in sola lettura. Qualsiasi verifica sul DB usa le viste USER_*/ALL_*; mai INSERT/UPDATE/DELETE, mai stampare segreti.
  4. Non tradurre gli identificatori tecnici (nomi di classi, progetti, tabelle, procedure): la prosa e' in italiano, gli identificatori restano come nel codice.
  5. Se correggi un fatto gia' registrato, aggiorna anche gli state file in docs/_state/ quando pertinente (claims.ndjson, conflicts.md, open-questions.md) e ricostruisci con build.sh (atteso 0/0).

Stile Markdown

  • Una frase per riga fisica (facilita le diff e le review). Mantieni la normale struttura Markdown.
  • Trattino semplice -, mai il trattino lungo.
  • Titoli e tabelle come nelle pagine esistenti dello stesso capitolo: guarda una pagina vicina prima di inventare un formato nuovo.

Riferimenti