La documentazione di progetto muore quasi sempre, e cosa cambia quando smettiamo di trattarla come un faldone di file e iniziamo a concepirla come uno spazio di ragionamento progettuale.
In quasi tutti i progetti software che durano più di qualche mese, la documentazione fa la stessa fine. Nasce con buone intenzioni, viene aggiornata per le prime due settimane, poi si stacca dal lavoro reale. Dopo qualche mese nessuno la apre più, e quando qualcuno prova a farlo scopre che racconta un sistema che non esiste più. Avevi un documento, ora hai un fossile inutile.
È un problema così comune che abbiamo smesso di considerarlo un problema. Lo trattiamo come una legge di natura: la documentazione invecchia, va fuori dai radar, e tra un piccolo intervento e l'altro diventa un repository di piccoli ammanchi informativi, fa parte del gioco. In realtà è un sintomo. Il sintomo di un equivoco di fondo sul senso pratico della documentazione in un progetto complesso.
L'equivoco è questo: pensiamo che documentare significhi archiviare. Mettere in ordine, raccogliere, catalogare. Ma in un progetto software vero la parte preziosa della conoscenza non è quella archiviabile, è quella relazionale. Non è il singolo documento, è il filo che lega una decisione tecnica a un vincolo di business, un bug a una scelta di tre mesi prima, un dubbio mai risolto a una milestone che si avvicina o, peggio, quella brillante intuizione che tradotta in logica avrebbe potuto arricchire il progetto di uno spropositato valore. Questa conoscenza non vive bene in un archivio. Vive in una rete di nodi informativi.
Ed è esattamente qui che strumenti come Obsidian iniziano a diventare interessanti non come l'ennesima app per prendere appunti, ma come un cambio di approccio.
Il problema non è (solo) lo strumento
La reazione tipica di chi si trova di fronte una documentazione fallita è cambiare strumento per trovare un nuovo modo di fallire. Da Word a Confluence, da Confluence a Notion, da Notion a un wiki interno. Ogni volta si pensa che il prossimo tool risolverà il problema. Ogni volta, dopo qualche mese, ci si ritrova allo stesso punto.
Il motivo è che questi strumenti, pur essendo molto diversi tra loro, condividono un'impostazione di fondo: sono gerarchici. Funzionano per cartelle, sezioni, sottosezioni. Sono ottimi per archiviare contenuti finiti come un manuale utente, una specifica firmata, un verbale. Sono molto meno bravi a far emergere relazioni, e in un progetto software le relazioni contano almeno quanto i contenuti.
Contano nello spazio dello sviluppo e nella prospettiva che lega l'idea al risultato.
Una decisione architetturale raramente vive da sola. Tocca un requisito, dipende da un vincolo, genera un rischio, condiziona un test, impatta una stima, si incrocia con un tema di sicurezza o di GDPR. Se la conoscenza progettuale è una rete e lo strumento è un albero, la rete viene tagliata ogni volta che proviamo a sistemarla in una cartella e gli errori si propagano fino a diventare parte del progetto stesso.
Obsidian come spazio di pensiero collegato
Obsidian parte da un'idea diversa. Non chiede di decidere subito dove va una nota. Chiede di scriverla, e poi di collegarla a ciò con cui ha a che fare. La struttura emerge dopo, dall'uso.
Tecnicamente è uno strumento semplice: file Markdown locali, link bidirezionali tra le note, una vista a grafo che mostra le connessioni. Niente database proprietario, niente cloud obbligatorio, niente lock-in. Una cartella di file di testo che puoi mettere in un repository Git come qualunque altro pezzo di codice.
Quello che cambia non è la tecnologia. È il movimento mentale. Negli strumenti gerarchici prima strutturi, poi pensi: devi sapere dove va una cosa per poterla scrivere. In Obsidian prima pensi, poi strutturi: scrivi la nota, la colleghi a quello che già esiste, e la struttura si forma da sola man mano che il progetto cresce. È un'inversione che sembra piccola e invece cambia il modo in cui la documentazione si accumula nel tempo.
Cosa significa nello sviluppo software
Nello sviluppo questa logica diventa concreta molto in fretta. Una nota per una decisione architetturale, una per un dubbio aperto, una per una convenzione di progetto, una per un concetto di dominio, una per un problema ricorrente. Niente di rivoluzionario, preso uno per uno. Ma quando queste note iniziano a linkarsi tra loro il requisito cita la decisione, la decisione richiama il rischio, il rischio rimanda al test ed emerge qualcosa che gli strumenti tradizionali fanno fatica a produrre: un tessuto di contesto che sopravvive al singolo sviluppatore e al singolo sprint. Un approccio che ritroviamo in tutti i nostri progetti di software su misura, dove la continuità della conoscenza vale quanto il codice.
Su ITER-PA, il nostro Albo Pretorio in cloud, lo stiamo usando esattamente così: ogni topic viene taggato per il mondo a cui appartiene: legale o tecnico, e i due piani restano collegati invece di vivere in microcosmi separati. Quando una norma cambia, la rete di note rende più semplice risalire ai punti del sistema che potrebbero esserne influenzati, mantenendo leggibile il collegamento tra vincolo normativo, scelta progettuale e implementazione. Quando una scelta tecnica nasce da un vincolo normativo, quel vincolo è a un click di distanza, non sepolto in una mail di sei mesi prima.
Sul nostro ERP interno l'uso è ancora più ibrido. Accanto ai file di sviluppo e ai changelog, la stessa rete di note ospita informazioni di gestione: marginalità, produttività, indicatori economici. Non per fare reportistica, per quello ci sono altri strumenti, ma per tenere insieme il piano tecnico e quello d'impresa, che nei progetti reali non sono mai davvero separati. Una scelta architetturale ha un costo, una funzionalità ha una marginalità, e poterli vedere nello stesso spazio cambia il modo in cui si prendono le decisioni.
In entrambi i casi va detta una cosa che spesso si dimentica quando si parla di questi strumenti: Obsidian non sta sostituendo niente. Il codice resta nel repository, i task restano negli strumenti che li gestiscono, le specifiche formali verso il cliente continuano a vivere dove devono vivere. Sarebbe un errore e, lo abbiamo visto succedere, usarlo come contenitore universale, riversarci dentro ogni cosa, trasformarlo nell'ennesimo posto dove le informazioni vanno a sedimentarsi senza più uscirne. Funziona finché resta nel suo perimetro: lo spazio in cui il ragionamento progettuale si deposita e si collega. Tutto il resto vive altrove, e fa bene a viverci.
Il valore vero: la continuità
Il valore di Obsidian, alla fine, non è la vista a grafo. Non sono i backlink, non è il Markdown, non è nessuna delle feature che vengono di solito raccontate negli articoli entusiasti.
Il valore è la continuità di pensiero. La possibilità di non perdere il filo tra una decisione e la sua ragione, tra un problema e il suo contesto, tra ciò che il sistema è oggi e ciò che era sei mesi fa. Obsidian, quando usato bene, diventa una specie di quadro iperuranico del progetto: uno spazio in cui idee, decisioni, dubbi e connessioni diventano visibili prima ancora di cristallizzarsi in documentazione formale.
Nei progetti software non basta sapere cosa è stato fatto. Bisogna sapere perché è stato fatto così. Quel "perché" è la cosa che si perde per prima quando la documentazione muore ed è la cosa che, solo una rete di note collegate riesce a tenere viva.
Per chi vuole sperimentare questo approccio, Obsidian è disponibile dal sito ufficiale: obsidian.md.