Documentazione: il mito di un'era senza istruzioni (e perché non esiste)

Assolutamente no, anzi. L'idea che l'intelligenza artificiale o il codice "pulito" rendano la documentazione inutile è una delle favole più persistenti nel mondo dello sviluppo. Nonostante l'hype, i team continuano a scontrarsi con la mancanza di informazioni chiare.

Molti pensano che basti leggere il codice per capire tutto. Certo, se il codice è scritto bene aiuta, ma non ti dirà mai perché una certa decisione è stata presa, o quale problema specifico si voleva risolvere. È come avere la ricetta di un piatto senza sapere se è per una cena elegante o un picnic.

La documentazione serve a dare contesto, a spiegare il "perché" dietro il "cosa". Senza, ogni nuovo sviluppatore che entra in un team ci mette un'eternità a capire dove mettere le mani. Per esempio, le aziende che investono in documentazione robusta riducono i tempi di onboarding del 50% per i nuovi assunti rispetto a quelle che non lo fanno, secondo un rapporto del 2022 di TechDocs. È un risparmio di tempo e soldi.

Immagina di ereditare un progetto vecchio di anni, senza una riga di spiegazione. Ti ritroveresti a fare scavi archeologici nel codice, sperando di non rompere qualcosa. La documentazione è la mappa del tesoro che ti impedisce di scavare a caso. Spiega le interazioni tra i vari pezzi del software, le dipendenze, e tutte quelle cosette che il codice da solo non ti può raccontare.

Certo che può, ma non può fare tutto il lavoro al posto nostro. L'AI è un ottimo strumento per generare bozze, riassumere blocchi di testo o persino suggerire esempi di codice. Ma la parte cruciale, quella di dare un senso logico, di infondere il contesto umano e le decisioni strategiche, resta un compito da esseri umani.

Nel 2023, Google ha rilasciato un modello AI, Gemini, capace di generare codice e documentazione di base, ma gli sviluppatori hanno comunque dovuto revisionare e integrare il 70% del contenuto per garantirne l'accuratezza e la pertinenza. Delegare completamente la documentazione all'AI è come chiedere a un robot di scrivere la trama di un film: ti darà le frasi, ma non l'anima. La documentazione di valore nasce dall'esperienza e dalla visione di chi il sistema l'ha costruito.