La documentazione tecnica viene spesso trattata come lavoro accessorio da rimandare. In realtà è uno degli strumenti più semplici per ridurre vendor lock-in, bus factor e tempi di onboarding. Il punto non è documentare tutto, ma documentare ciò che sarebbe costoso ricostruire.
Il minimo utile
Ogni progetto dovrebbe permettere di capire come è fatto, come si avvia, come si rilascia e quali sistemi esterni utilizza.
- Schema architetturale
- Setup locale e ambienti
- Processo di build e deploy
- Servizi esterni e credenziali
- Backup e restore
- Decisioni tecniche non ovvie
Documentare decisioni, non solo procedure
Sapere che una tecnologia è presente non basta. Le decisioni importanti dovrebbero conservare anche motivazioni, alternative considerate e vincoli, per evitare di ripetere discussioni già fatte.
Trattarla come parte del delivery
La documentazione invecchia se è un’attività separata. È più sostenibile aggiornarla insieme alle modifiche che cambiano architettura o procedure operative.
Se per capire come pubblicare il software bisogna telefonare alla persona “che sa tutto”, la documentazione non è sufficiente.
Vuoi applicarlo al tuo progetto?
Possiamo partire da una valutazione del contesto attuale e capire quali decisioni hanno priorità.
Approfondisci Software AssessmentDomande frequenti
Serve documentare ogni classe o funzione?
No. La priorità è ciò che serve a comprendere architettura, dipendenze, procedure e decisioni non evidenti.
Dove conviene conservare la documentazione?
Vicino al codice per gli aspetti tecnici operativi; un knowledge base separato può essere utile per procedure e contesto più ampio.