Mappe, oro e spezie: perché trascurare la documentazione può far naufragare il tuo progetto

Quale era il bene più prezioso che gli esploratori di un tempo riportavano a casa dai loro viaggi? Oro e spezie? Sbagliato. Mappe.

Cristoforo Colombo non avrebbe mai fatto il suo famoso viaggio nel 1492 senza un mappa progettato dai suoi predecessori. Un gioco di spionaggio per ottenere mappe portoghesi gettò le basi per la Compagnia olandese delle Indie orientali, probabilmente la compagnia più costosa della storia umana. Al suo apice nel 1637, valeva 78 milioni di fiorini olandesi, un equivalente di 7,9 trilioni di dollari in dollari del 2017. Sono più di 10 trilioni di dollari in denaro del 2024, più di Microsoft , Nvidia e Apple combinato I tesori tangibili provenienti da nuove terre erano importanti nel breve periodo, ma in una prospettiva a lungo termine era la conoscenza a forgiare vere fortune.

Come mai nel mondo tecnologico odierno tendiamo a dimenticarlo? Inseguendo il successo immediato, siamo spesso restii a dedicare tempo e risorse preziose alla produzione e al mantenimento della documentazione tecnica. Parlando in termini del XVII secolo, ci precipitiamo ad accaparrarci oro e spezie senza tracciare le nostre mappe che, a loro volta, avrebbero potuto condurci a molto più oro e spezie. Siete scettici? Ahoy, diamo un'occhiata più da vicino...

Codice stravagante

"Come senza dubbio ricorderai, la stasi ipnoide dei modelli neuronici del cervello può essere scansionata da un raggio extra-elettromagnetico che..." "Dai!" disse Ard Vark impazientemente. "Cosa intendi con "come senza dubbio ricordiamo?" Come possiamo ricordarlo se non lo abbiamo mai saputo? - Questa citazione da Wacky World, un racconto del grande scrittore di fantascienza Edmond Hamilton, si riferisce ai marziani, non ai programmatori. Tuttavia, molte persone vedono gli sviluppatori come se provenissero da un altro pianeta, specialmente quelli che hanno solo una vaga idea dello sviluppo del software e delle sue complessità. Il fatto è che gli sviluppatori spesso presumono che gli altri conoscano il codice tanto bene quanto loro e spesso considerano la documentazione tecnica non necessaria. Questa mentalità rischia di rendere il progetto complesso e incomprensibile per gli estranei come una "stasi ipnoide", mettendo in definitiva a repentaglio il potenziale successo del progetto.

La riluttanza a creare documentazione spesso deriva dalle stesse ragioni per cui le persone rimandano in altri ambiti: richiede molto tempo e investimenti finanziari. In altre parole, è spesso dovuta a pura pigrizia e desiderio di risparmiare denaro, che non sono ostacoli facili da superare. Tuttavia, la documentazione non è solo un'informazione ridondante che è presumibilmente ovvia per tutti; contiene dettagli critici che possono essere indispensabili. Spesso, l'assenza di documentazione complica notevolmente il rilevamento e la correzione degli errori, rende più difficili la manutenzione e gli aggiornamenti e aumenta il tempo necessario per l'inserimento di nuovi membri del team. Mentre i team senza documentazione sono bloccati in attività ripetitive, i progetti con documentazione ben strutturata mostrano elevata efficienza e affidabilità: questo è un fatto, non una semplice opinione.

Sì, alcuni programmatori sostengono che il codice che scrivono è così chiaro e comprensibile che la documentazione è semplicemente inutile. Tuttavia, in realtà, anche il codice più perfetto può confondere gli altri o perdere la sua chiarezza nel tempo. Ciò che sembra chiaro oggi può diventare un enigma domani. Ad esempio, potresti facilmente gestire una semplice scheda perforata degli anni '70?

Fattore bus, burnout e altre bestie fantastiche

La teoria è buona, ma la pratica è più convincente. Ecco alcuni esempi, basati su storie vere, con solo i nomi di persone e aziende fittizi. Questi brevi casi di studio coprono i problemi più tipici che sorgono a causa di scarse pratiche di documentazione tecnica.

Storia n. 1: Incapacità di scalare

Il progetto "NoDocumentationPlease", inizialmente una startup di streaming video di successo, ha dovuto affrontare seri problemi nel tentativo di scalare a causa della scarsa documentazione tecnica. Quando il team ha dovuto espandersi, i nuovi dipendenti non riuscivano a comprendere appieno i loro compiti e nessuno era in grado di fornire loro una spiegazione adeguata. Senza un adeguato supporto e formazione, i nuovi assunti se ne sono andati rapidamente. Ciò non solo ha rallentato i progressi del progetto, ma ha anche portato alla perdita di talenti chiave, mettendo a repentaglio l'efficacia complessiva e il futuro del progetto. Di conseguenza, gli streamer hanno abbandonato la chat e il progetto è stato chiuso.

Storia n. 2: Problemi di manutenzione

L'azienda "IKnowEverything" ha sviluppato una piattaforma cloud per la sincronizzazione e l'archiviazione dei dati. Inizialmente, il progetto è progredito rapidamente, ma nel tempo, i suoi sviluppatori hanno avuto difficoltà a mantenere e aggiornare la piattaforma a causa della mancanza di una documentazione tecnica chiara e aggiornata. Ciò ha portato a uno sviluppo più lento, più bug e clienti insoddisfatti. Alla fine, l'azienda ha iniziato a perdere i suoi vecchi clienti e i nuovi clienti hanno scelto concorrenti con soluzioni più stabili e affidabili. I ricavi sono diminuiti in modo significativo mentre il costo della manutenzione inefficace è aumentato. Documentare correttamente gli aspetti tecnici fin dall'inizio avrebbe potuto consentire loro di scalare con successo. Tuttavia, non è stato fatto in tempo. Di conseguenza, l'azienda non è riuscita a superare le sfide tecniche e finanziarie ed è stata chiusa.

Storia n. 3: Esaurimento degli sviluppatori

Il progetto "SmartestEver" ha dovuto affrontare gravi problemi perché il suo sviluppatore principale, Andrew, che si occupava praticamente di tutto, si è dimesso dopo essere stato sopraffatto dalle numerose domande del team. Se "SmartestEver" avesse avuto una documentazione adeguata, gli sviluppatori junior avrebbero potuto facilmente fare riferimento alle FAQ e risolvere i problemi di routine. Invece, hanno bombardato Andrew di domande e, senza di lui e la documentazione necessaria, il team non è riuscito ad andare avanti e il progetto è stato chiuso (premere F per Andrew).

Storia n. 4: Fattore autobus

Nella società "NoDocsNeeded", un promettente prodotto software era in fase di sviluppo da parte di John, uno sviluppatore chiave, che deteneva tutte le conoscenze ma non si preoccupava di documentarle. Nemmeno i suoi manager si preoccuparono di convincerlo. Arrivò un giorno in cui John partì per un viaggio di lavoro e non tornò più. Senza documentazione o comprensione dell'architettura e della logica del prodotto, i membri rimanenti del team non riuscirono praticamente a fare nulla. Il progetto fu congelato e il denaro investito in esso fu sprecato. La lezione è semplice: la documentazione e la distribuzione delle conoscenze all'interno di un team sono fondamentali per evitare di dipendere da una singola persona. A proposito, stanno ancora cercando John...

Storia n. 5: Nessun profeta è benvenuto nell'Open Source

Maria creò la sua prima libreria open source ma non scrisse alcuna documentazione per essa. Nessuno capì cosa facesse la libreria e Maria decise che non ne avrebbe scritte altre perché le sembrava inutile. Il progetto di Maria finì prima ancora di iniziare e decise di cambiare professione.

Da mozzo a capitano

Ok, abbiamo un po' di teoria e pratica, ora immergiamoci nella ricerca e nelle statistiche. Stack Overflow Developer Survey 2024 stati che l'84% degli intervistati usa la documentazione tecnica per comprendere la funzionalità delle tecnologie. Tuttavia, anche con la documentazione, spesso non riescono a trovare le risposte di cui hanno bisogno, come dimostrano le risorse più popolari: Stack Overflow (80%), Tutorial scritti (68%), blog (61%) e video tutorial (54%). Microsoft Research: The Daily Life of Software Developers trovato che, in media, gli sviluppatori dedicano l'1-2% della loro giornata (8-10 minuti) alla documentazione e il 10,3% degli sviluppatori afferma che la documentazione obsoleta li costringe a dedicare troppo tempo alla ricerca di risposte da soli. La necessità della documentazione è una preoccupazione importante anche per la comunità accademica. Una semplice ricerca su Google Scholar per <"documentazione" AND "software"> rendimenti oltre 4 milioni di risultati, il che indica chiaramente un vasto numero di pubblicazioni scientifiche che affrontano la questione.

Le conclusioni principali sono sorprendentemente semplici: #1 – Tutti hanno bisogno di documentazione quando si tratta di comprendere la tecnologia e/o il lavoro di altre persone; ma #2 – Poche persone si preoccupano di scriverla e mantenerla; e di conseguenza #3 – Molta documentazione è scritta male, obsoleta e generalmente inutile. Quindi cosa bisogna fare? Cambiare la propria motivazione a tutti i livelli.

Un gruppo di ricercatori dell'Università di Scienze Applicate HAN e dell'Università di Groninga (entrambe nei Paesi Bassi) identificato i problemi più tipici con la documentazione tecnica:

• La documentazione informale spesso utilizzata dagli sviluppatori è difficile da comprendere;

• La documentazione è considerata uno spreco quando non contribuisce immediatamente al prodotto finale;

• La produttività di uno sviluppatore si misura solo in base alla quantità di software funzionante;

• Spesso la documentazione non è sincronizzata con il software effettivo;

• Spesso gli sviluppatori mantengono solo un focus a breve termine, soprattutto negli ambienti di sviluppo software continuo.

  
  

Vi suona familiare? Scommetto che la maggior parte di noi si è imbattuta nella maggior parte o addirittura in tutti questi problemi contemporaneamente nel nostro lavoro quotidiano di routine. E c'è di più di una semplice procrastinazione o mancanza di risorse. Alcuni di questi problemi derivano da una mancanza di gestione adeguata, pianificazione a lungo termine e, in ultima analisi, di visione strategica. Ed ecco la parte difficile, perché non spetta solo a noi sviluppatori risolvere. Alcuni problemi dovrebbero essere affrontati dai manager, dagli stakeholder del prodotto o persino dai proprietari dell'azienda. Ecco perché è fondamentale che le giuste opinioni sulla tecnica non siano solo un bell'accessorio, ma parte dei valori fondamentali dell'intera azienda, condivisi da tutti, dai fondatori agli sviluppatori junior.