Repository Documentation

Mai sentito parlare di “documentation debt”? È quel fenomeno misterioso dove la documentazione invecchia più velocemente di un avocado sul bancone della cucina. Ma non temere! Oggi esploreremo come mantenere la documentazione fresca, aggiornata e - sorprendentemente - utile, tutto direttamente nel tuo repository.

Dimenticati delle wiki esterne che nessuno aggiorna e dei documenti condivisi che si perdono nel vuoto cosmico del cloud. È tempo di portare la documentazione dove appartiene: proprio accanto al codice che descrive.

📚 Perché nel Repository?

Mantenere la documentazione nel repository è come avere il manuale d’istruzioni attaccato al telecomando: è sempre lì quando serve e si aggiorna quando cambi le batterie. I vantaggi?

• Versionamento automatico (addio a “documentazione_finale_v3_definitiva_questa_volta_davvero.doc”)
• Code review che includono la documentazione (non si scappa!)
• Single source of truth (niente più scuse del tipo “ah, ma quella era la vecchia versione”)

🗂️ Tipi di Documentazione

Derivazioni e Dipendenze 🔄

Questo non è un albero genealogico dei microservizi, ma ti aiuta a capire chi parla con chi!

Documentazione Testuale 📝

Manuale

Il buon vecchio markdown scritto a mano, per quando devi spiegare concetti complessi:

1# Nome del Servizio
2
3## Setup Locale
41. Clona il repository
52. Installa le dipendenze: `npm install`
63. Configura le variabili d'ambiente: `cp .env.example .env`
7
8## Architettura
9Il servizio utilizza un'architettura event-driven con…

Autogenerata dal Codice 🤖

Con JSDoc puoi generare documentazione direttamente dai commenti:

 1/**
 2 * Gestisce l'autenticazione degli utenti
 3 * @param {string} username - Username dell'utente
 4 * @param {string} password - Password in chiaro
 5 * @returns {Promise<User>} Oggetto utente autenticato
 6 * @throws {AuthError} Se le credenziali non sono valide
 7 */
 8async function authenticateUser(username: string, password: string): Promise<User> {
 9  // …
10}

Per TypeScript, puoi usare TypeDoc:

1typedoc src/index.ts --out docs

API Documentation 📡

OpenAPI/Swagger è il tuo migliore amico qui. Esempio:

1openapi: 3.0.0
2info:
3  title: Il Mio Fantastico Servizio
4  version: 1.0.0
5paths:
6  /magically-works:
7    get:
8      summary: Endpoint che funziona per magia

Diagrammi Architetturali 🏗️

Perché una immagine vale più di mille parole (e mille meeting):

🔍 Strumenti di Validazione della Documentazione

📝 Vale: Controllo Grammaticale e Stile

Vale è un validatore di prosa che ti aiuta a mantenere uno stile di scrittura coerente e corretto.

Installazione

1brew install vale

Configurazione

Crea un file .vale.ini nella root:

1StylesPath = styles
2MinAlertLevel = suggestion
3
4[*.md]
5BasedOnStyles = proselint, write-good, vale

📋 Markdownlint: Formattazione e Consistenza

Markdownlint-cli2 assicura che il tuo Markdown segua le convenzioni standard e mantenga una formattazione coerente.

Installazione

1brew install markdownlint-cli2

Configurazione

Crea un file .markdownlint.json nella root:

1{
2  "default": true,
3  "MD013": false,
4  "MD033": false,
5  "MD041": false,
6  "MD024": false,
7  "MD046": false
8}

🪝 Git Hooks per la Validazione Automatica

I Git Hooks ci permettono di eseguire controlli automatici prima di ogni commit.

Configurazione dei Git Hooks

Crea la directory .githooks e il file pre-commit:

1mkdir .githooks
2touch .githooks/pre-commit
3chmod +x .githooks/pre-commit

Configura il contenuto del pre-commit hook:

 1#!/bin/sh
 2FILES=$(git diff --cached --name-only | grep '\.md$')
 3if [ -n "$FILES" ]; then
 4    # Controllo Vale
 5    vale $FILES
 6    if [ $? -ne 0 ]; then
 7        echo "❌ La documentazione non passa i controlli di Vale"
 8        exit 1
 9    fi
10    
11    # Controllo Markdownlint
12    markdownlint-cli2 $FILES
13    if [ $? -ne 0 ]; then
14        echo "❌ La documentazione non passa i controlli di Markdownlint"
15        exit 1
16    fi
17fi

Attiva gli hooks:

1git config core.hooksPath .githooks

🚀 Automazione è la Chiave

Integra la validazione della documentazione nella tua CI:

1documentation:
2  script:
3    - vale content/**/*.md
4    - markdownlint-cli2 "content/**/*.md"
5  only:
6    - merge_requests

Perché la documentazione è come il codice: se non la testi, non puoi fidarti!

🎭 Best Practices (o “Come Non Farsi Odiare dai Colleghi”)

Update Insieme al Codice 📝

• Se modifichi una feature, aggiorna la sua documentazione
• Se deprechi qualcosa, documentalo (non lasciare trappole)

Keep It DRY 🌵

• Usa riferimenti incrociati
• Centralizza le informazioni comuni
• Automatizza la generazione dove possibile

Struttura Chiara 🗂️

• README.md in ogni directory importante
• Indice dei contenuti per repository grandi
• Link tra documenti correlati

💡 Conclusione

La documentazione nel repository non è solo una best practice, è un atto di gentilezza verso il tuo io futuro e i tuoi colleghi. E ricorda: “Il codice dice cosa fa, la documentazione dice perché lo fa” (e qualche volta anche come fa a farlo, quando il codice è particolarmente criptico).