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
2
3
4
5
6
7
8
9

# Nome del Servizio

## Setup Locale
1. Clona il repository
2. Installa le dipendenze: `npm install`
3. Configura le variabili d'ambiente: `cp .env.example .env`

## Architettura
Il servizio utilizza un'architettura event-driven con…

Autogenerata dal Codice 🤖

Con JSDoc puoi generare documentazione direttamente dai commenti:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

Per TypeScript, puoi usare TypeDoc:

1

typedoc src/index.ts --out docs

API Documentation 📡

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

1
2
3
4
5
6
7
8

openapi: 3.0.0
info:
  title: Il Mio Fantastico Servizio
  version: 1.0.0
paths:
  /magically-works:
    get:
      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

1

brew install vale

Configurazione

Crea un file .vale.ini nella root:

1
2
3
4
5

StylesPath = styles
MinAlertLevel = suggestion

[*.md]
BasedOnStyles = 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

1

brew install markdownlint-cli2

Configurazione

Crea un file .markdownlint.json nella root:

1
2
3
4
5
6
7
8

{
  "default": true,
  "MD013": false,
  "MD033": false,
  "MD041": false,
  "MD024": false,
  "MD046": false
}

🪝 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:

1
2
3

mkdir .githooks
touch .githooks/pre-commit
chmod +x .githooks/pre-commit

Configura il contenuto del pre-commit hook:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

#!/bin/sh
FILES=$(git diff --cached --name-only | grep '\.md$')
if [ -n "$FILES" ]; then
    # Controllo Vale
    vale $FILES
    if [ $? -ne 0 ]; then
        echo "❌ La documentazione non passa i controlli di Vale"
        exit 1
    fi
    
    # Controllo Markdownlint
    markdownlint-cli2 $FILES
    if [ $? -ne 0 ]; then
        echo "❌ La documentazione non passa i controlli di Markdownlint"
        exit 1
    fi
fi

Attiva gli hooks:

1

git config core.hooksPath .githooks

🚀 Automazione è la Chiave

Integra la validazione della documentazione nella tua CI:

1
2
3
4
5
6

documentation:
  script:
    - vale content/**/*.md
    - markdownlint-cli2 "content/**/*.md"
  only:
    - 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).