Documentazione mancante nel software: come recuperarla nel 2026

“Il nostro gestionale lo gestiva solo lui, adesso se n’è andato e non c’è scritto niente da nessuna parte.”
Questa situazione è più comune di quanto si pensi. Un software aziendale costruito nel tempo, magari da un singolo sviluppatore o da un fornitore esterno che non ha mai consegnato nulla di scritto, diventa una scatola nera nel momento in cui la persona che lo conosce non c’è più. Recuperare quella conoscenza è possibile, ma richiede metodo. Questa guida ti porta attraverso i passi operativi, con le trappole più frequenti indicate dove capitano.

Prima di tutto: capire cosa manca davvero

Non tutta la documentazione ha lo stesso peso. Prima di mettersi a scrivere qualsiasi cosa, serve capire dove si trova il buco più pericoloso.
Ci sono tre livelli distinti. Il primo è la documentazione tecnica: architettura del sistema, struttura del database, dipendenze esterne, credenziali di accesso, procedure di deploy. Il secondo è la documentazione funzionale: cosa fa ogni parte del software, quali regole di business applica, quali casi limite gestisce. Il terzo è la documentazione operativa: come si usa, chi fa cosa, cosa succede quando qualcosa va storto.
Spesso mancano tutti e tre. Però il primo livello è quello che blocca immediatamente il lavoro tecnico; il secondo è quello che crea problemi nei mesi successivi quando si deve modificare qualcosa; il terzo è quello che il team operativo sente di più ogni giorno.
Cosa va storto qui: si parte subito a scrivere documentazione tecnica perché sembra la più “seria”, e si trascura la documentazione funzionale. Poi, quando arriva la prima modifica al software, si scopre che nessuno ha scritto perché una certa regola è stata implementata in quel modo.

Passo 1: audit di quello che esiste già

Prima di produrre qualcosa di nuovo, cerca quello che c’è. Spesso la documentazione esiste, ma è sparsa e non riconosciuta come tale.
Guarda in questi posti: email dei vecchi sviluppatori, ticket di assistenza, commenti nel codice sorgente, file README anche parziali, manuali Word o PDF mai aggiornati, fogli Excel con logiche di calcolo, presentazioni PowerPoint fatte per il management. Anche una mail del 2019 che spiega perché è stata aggiunta una certa funzione è documentazione.
Raccogli tutto in un unico posto, anche temporaneo. Un semplice documento condiviso o una cartella su un servizio di archiviazione cloud va benissimo come deposito iniziale.
Cosa va storto qui: si sottovaluta questo passaggio e si ricomincia da zero. Risultato: si scrivono cose già scritte altrove, e si perdono informazioni che erano già disponibili.

Passo 2: intervistare chi usa il software ogni giorno

Il codice dice cosa fa il software. Le persone che lo usano sanno perché funziona così e cosa succede quando non funziona.
Organizza sessioni brevi, da 30 a 60 minuti, con gli utenti principali di ogni area. Non chiedere “come funziona il software”: è una domanda troppo aperta. Chiedi invece cose specifiche: “Cosa fai il lunedì mattina appena apri il gestionale?”, “Quando ti blocchi, cosa fai?”, “Ci sono cose che fai sempre nello stesso ordine e non sai perché?”.
Registra le sessioni (con il consenso), oppure prendi note strutturate. L’obiettivo non è scrivere documentazione durante l’intervista: è raccogliere materia prima da elaborare dopo.
Cosa va storto qui: si intervistano solo i responsabili, che spesso conoscono meno bene le operazioni quotidiane rispetto a chi usa il software otto ore al giorno. Parla con chi lavora sul campo.

Passo 3: reverse engineering del codice

Se hai accesso al codice sorgente, puoi usarlo per ricostruire una parte della documentazione tecnica. Questo passaggio richiede uno sviluppatore, non è qualcosa che si fa a mano.
Ci sono strumenti che analizzano il codice e producono automaticamente diagrammi delle classi, mappe delle dipendenze, schemi del database. Non producono documentazione leggibile da un umano, però forniscono una base su cui lavorare.
Il reverse engineering risponde alla domanda “cosa fa questo codice”. Non risponde alla domanda “perché è stato scritto così”. Quella risposta viene solo dalle interviste e da quello che si trova nell’audit del passo 1.
Opinione netta: chi vende il reverse engineering automatico come soluzione completa alla documentazione mancante sta sopravvalutando lo strumento. Gli output automatici sono un punto di partenza, non un risultato. Senza una revisione umana, producono documentazione che descrive il codice ma non il business.
Cosa va storto qui: ci si ferma all’output automatico e si pensa di aver finito. Poi il primo sviluppatore che legge quella documentazione per fare una modifica si accorge che manca il contesto che conta.

Passo 4: prioritizzare per rischio, non per completezza

Documentare tutto subito è irrealistico. Serve una priorità basata su cosa può bloccare il business se va storto.
Parti dai processi critici: quelli che generano fatturato, quelli che gestiscono dati regolamentati (privacy, fiscale, qualità), quelli che si rompono con più frequenza. Per ognuno, scrivi prima la documentazione minima che permette a un nuovo sviluppatore di capire cosa toccare senza rompere niente.
La documentazione completa arriva nel tempo, aggiornandola ogni volta che si fa una modifica al software. Se aspetti di avere tutto prima di pubblicare qualcosa, non pubblicherai mai niente.
Cosa va storto qui: si vuole fare tutto insieme e si produce un documento enorme che nessuno legge. Meglio dieci pagine usate che cento pagine ignorate.
Se stai valutando se il tuo software vale la pena di essere documentato o se è arrivato il momento di riscriverlo, leggi la guida sul refactoring software legacy prima di decidere.

Passo 5: scegliere dove tenere la documentazione

La documentazione che vive in un Word sul desktop di qualcuno non esiste. Serve un posto accessibile, versionato e aggiornabile.
Le opzioni sono poche e concrete. Un wiki interno (Notion, Confluence, o anche una cartella GitHub con file Markdown) funziona se il team lo usa davvero. Un repository git con documentazione vicina al codice funziona bene per la parte tecnica. Una base di conoscenza nel sistema di ticketing funziona per la parte operativa.
La scelta dello strumento conta meno della disciplina di aggiornamento. Qualsiasi strumento si usa, serve una regola esplicita: ogni modifica al software porta con sé un aggiornamento alla documentazione corrispondente. Senza questa regola, la documentazione diventa obsoleta in poche settimane.
Cosa va storto qui: si sceglie lo strumento più sofisticato invece di quello che il team usa già. Se tutti aprono Notion ogni giorno, metti la documentazione lì. Se nessuno apre Confluence, non importa quanto sia potente.

Passo 6: mantenere la documentazione viva

Una documentazione scritta una volta e mai aggiornata è peggio di nessuna documentazione. Porta a decisioni sbagliate basate su informazioni false.
Il modo più pratico per mantenerla è legarla al processo di sviluppo. Ogni volta che si apre un ticket di modifica, si verifica se la documentazione relativa è aggiornata. Ogni volta che si fa una code review, si controlla se i commenti nel codice riflettono ancora il comportamento reale.
Questo richiede tempo, ma è un investimento che si ripaga ogni volta che un nuovo sviluppatore deve capire come funziona un modulo senza dover chiedere a qualcuno.
Per capire come strutturare un piano di manutenzione che includa anche la documentazione, la guida sulla manutenzione software custom copre questo aspetto in dettaglio.

Cosa fare se il fornitore non collabora

A volte il problema non è solo la mancanza di documentazione: è che il fornitore che ha sviluppato il software non vuole consegnarla, o non riesce a produrla perché non l’ha mai scritta.
In questo caso, i passi da seguire sono diversi. Prima di tutto, verifica cosa dice il contratto: la proprietà del codice e della documentazione dovrebbe essere specificata. Se il contratto non lo dice, sei in una posizione più debole ma non senza opzioni.
Se hai accesso al codice sorgente, puoi procedere con i passi descritti sopra anche senza la collaborazione del fornitore. Se non hai accesso al codice, la situazione è più seria: in quel caso, la guida sul cambio fornitore software descrive come gestire la transizione e cosa richiedere formalmente.
Cosa va storto qui: si aspetta che il fornitore consegni spontaneamente qualcosa. Se non lo ha fatto fino ad ora, non lo farà senza una richiesta esplicita e documentata.

Domande frequenti

Q: Da dove si comincia quando un software aziendale non ha nessuna documentazione?
A: Si parte da un audit rapido: raccogliere tutto quello che esiste, anche email, manuali Word, commenti nel codice, e mappare i processi critici. Solo dopo si decide cosa ricostruire per primo, partendo da ciò che blocca il lavoro se va storto.
Q: Quanto tempo serve per ricostruire la documentazione di un software legacy?
A: Dipende dalla dimensione del codice e da quanta conoscenza è ancora in testa alle persone. Un modulo di medie dimensioni richiede qualche settimana di lavoro dedicato. Un sistema completo può richiedere qualche mese, specialmente se chi lo conosce non è più disponibile.
Q: Il reverse engineering del codice è affidabile per ricostruire la documentazione?
A: È un punto di partenza utile, non una soluzione completa. Il codice dice cosa fa il software, non perché è stato fatto così. La logica di business va sempre verificata con chi lo usa ogni giorno, altrimenti si documenta il codice senza documentare il business.
Q: Vale la pena documentare un software che si prevede di sostituire?
A: Sì, quasi sempre. Anche se il software verrà sostituito, la documentazione serve per capire i requisiti del nuovo sistema e per non perdere regole di business che altrimenti andrebbero riscoperte dopo il go-live, spesso a caro prezzo.

Se ti trovi a gestire un software aziendale senza documentazione e non sai da dove partire, in Press Start possiamo fare un audit tecnico per capire cosa esiste, cosa manca e cosa va recuperato per primo. Raccontaci il tuo caso.