Quando la documentazione è troppo tecnica per chi fa IT

Esiste un paradosso affascinante nel mondo dello sviluppo software. Professionisti con “Information Technology” stampato sul biglietto da visita che dichiarano che la documentazione tecnica è “troppo tecnica”. Non stiamo parlando di persone catapultate per caso in un’azienda tecnologica, ma di figure che dovrebbero avere competenze specifiche nel settore. Eppure, questa frase risuona regolarmente nelle sale riunioni.

Questa situazione rivela una verità scomoda: molti che parlano di tecnologia non hanno mai affrontato veramente la complessità delle scelte tecniche. Si limitano a ripetere frasi fatte senza comprendere cosa si cela dietro ogni decisione architetturale, ogni scelta di implementazione, ogni trade-off tecnico.

Il problema non è la complessità intrinseca della tecnologia. È che in molte organizzazioni IT le persone vengono promosse o assunte in ruoli tecnici basandosi più su abilità politiche che competenze reali. Il risultato sono manager tecnici che non capiscono la tecnologia che dovrebbero gestire e che nascondono questa lacuna dietro frasi come “è troppo tecnico” o “facciamo una versione più semplice”.

I due estremi della documentazione

La gestione della documentazione tende verso due estremi ugualmente disfunzionali. Da una parte l’approccio enciclopedico: produrre tonnellate di documenti con titoli simili ma contenuti diversi, sparsi in cartelle con nomi creativi tipo “Documentazione_Finale_V3_Questa_Volta_Davvero_NEW”.

Documenti talmente dettagliati che leggerli tutti richiederebbe una vita umana. L’evoluzione moderna prevede l’uso di AI generativa per produrre testo soporifero, formalmente diverso ma sostanzialmente identico. Quantità che sostituisce qualità.

All’estremo opposto c’è la scuola del “tanto chi la legge”, dove la documentazione è vista come perdita di tempo. Qui regna la minuta, quella email riassuntiva che dovrebbe miracolosamente sostituire un’intera analisi funzionale.

Le minute del nulla

Il contenuto di queste minute è un capolavoro di vaghezza. “Verificare con l’ufficio competente”, “Fare un check”, “Approfondire questo aspetto”. Traduzione: “Nessuno sa come funzioni e nessuno vuole decidere”.

È un gioco dell’oca dove ogni casella rimanda a qualcun altro. Le decisioni vere non vengono mai prese, solo rimandate. Queste minute creano l’illusione di progresso senza produrre progresso reale.

L’analista che decide al posto di tutti

In questo vuoto decisionale entra l’analista funzionale. Spesso uno sviluppatore prestato al ruolo, costretto a scavare tra le ambiguità. Non può aspettare che i responsabili prendano le redini.

Deve colmare il vuoto decisionale, fingendosi l’autorità che manca. Raccoglie informazioni frammentarie, deduce requisiti da conversazioni vaghe, interpreta silenzi come consensi. Poi, con modestia apparente, chiede conferma: “Sono sulla strada giusta?”

Fa scelte sensate basate sulla propria esperienza, presentandole come decisioni collegiali. “Come avevamo discusso…” (che nessuno ricorda). “Come suggerito dal management…” (che non ha mai suggerito nulla).

E se il progetto va male? Ovviamente è colpa degli sviluppatori lenti. Mai dei manager che non hanno deciso nulla.

Il rituale dell’approvazione vuota

Nonostante il caos, l’analisi funzionale ottiene invariabilmente approvazioni entusiastiche. Ovviamente senza che nessuno abbia realmente letto quello che è stato scritto.

Il documento diventa protagonista di un rituale burocratico. Si sfoglia sommariamente, poi “Ottimo, approvato!” e si proclama il successo della fase di analisi.

Questo riflette un sistema dove l’approvazione è formalità per certificare scelte ovvie, non frutto di analisi critica. Approvare entusiasticamente ciò che nessuno ha letto è segnale di fiducia nel processo quanto di compiacenza nell’ignoranza condivisa.

Il mito dei linguaggi formali

L’accademia insegna linguaggi estremamente formali come panacea per i requisiti. Meno parole discorsive, più simboli e formule, per eliminare ogni ambiguità.

La teoria è affascinante: precisione chirurgica, specifiche matematicamente inconfutabili. La realtà è diversa. Molti hanno rifiuto psicologico verso documenti con termini tecnici.

La presenza di formule matematiche fa scattare terrore negli stakeholder, come se stessero per leggere istruzioni per astronavi aliene. La precisione teorica diventa ostacolo pratico alla collaborazione.

Il divario comunicativo

Il paradosso è evidente. Mentre in teoria la formalizzazione elimina equivoci, nella pratica crea un divario insormontabile. Precisione chirurgica da un lato, alienazione completa dall’altro.

Meeting si bloccano quando compaiono formule. Stakeholder si disimpegnano perché non comprendono il linguaggio. La precisione diventa ostacolo alla collaborazione.

Nella quotidianità il compromesso si impone. Si bilancia precisione con semplicità, adottando linguaggio ibrido che rispetta la logica formale ma resta comprensibile.

L’equilibrio necessario

Non esiste soluzione universale. Mentre alcuni apprezzano rigidità dei linguaggi formali, altri trovano conforto in un linguaggio discorsivo che, pur rischiando ambiguità, permette un’interazione più naturale.

I progetti IT non sono solo numeri e simboli, ma persone che collaborano imperfettamente e trasformano idee in soluzioni. La comunicazione deve essere adattabile.

La vera sfida è trovare l’equilibrio. Documentazione abbastanza precisa da essere utile, abbastanza accessibile da essere letta. Abbastanza formale da evitare ambiguità pericolose, abbastanza discorsiva da non alienare chi deve approvarla.

Il paradosso irrisolvibile

Alla fine ci ritroviamo in una situazione paradossale. Manager che trovano la documentazione troppo tecnica mentre sfogliano PDF che non leggeranno mai. Analisti che devono decidere tutto fingendo che le decisioni vengano dall’alto. Documenti approvati entusiasticamente senza essere stati compresi.

Nel mondo IT la differenza tra dire e fare è abissale. Tra l’essere troppo tecnico e ridurre tutto a email c’è un mondo di sfumature che solo chi è immerso nel mestiere può comprendere.

Per avanzare bisogna sempre inventarsi soluzioni sul momento, mentre le vere decisioni restano un mistero. L’importante non è capire, ma far sembrare di aver capito. È un gioco di apparenze dove tutti fingono di sapere cosa stanno facendo, ma in realtà navigano a vista sperando che qualcuno alla fine prenda davvero il controllo.

Gli eroi invisibili

In questo caos, i veri eroi sono gli analisti funzionali. Tra una riunione e l’altra, riescono a dare senso al disordine. Fanno sembrare che ogni decisione sia il risultato di una strategia impeccabile.

Trasformano e-mail vaghe in requisiti concreti. Traducono desideri nebulosi in specifiche implementabili. Colmano il vuoto lasciato da chi dovrebbe decidere ma non decide mai.

Tengono in piedi progetti che altrimenti crollerebbero sotto il peso delle non-decisioni. Meriterebbero riconoscimento, ma devono accontentarsi della soddisfazione di aver trasformato il caos in ordine.

Questo articolo è tratto da “Non funziona niente! – I progetti IT in crisi”, il primo libro della collana Nothing Works! — una tragicommedia aziendale per chi ha visto troppi Gantt chart trasformarsi in fiction.

Scopri la collana completa, gli altri libri e le prossime uscite su nothingworks.it

Vuoi il libro subito? Compralo su Amazon

Potrebbe interessarti anche

• Sistemista IT in una PMI: mansioni e competenze
• DIRETTORE ACQUISTI
• Perché documentare gli interventi IT potenzia la posizione del Sistemista?
• Da sistemista IT a IT Manager: un, possibile, percorso di carriera nell’ambito manifatturiero
• I problemi quotidiani di un Sistemista IT e come risolverli
• SISTEMISTA
• Quanto guadagna un Sistemista a Torino?
• SISTEMISTA IT
• Cosa fa un Sistemista in un Managed Service Provider: ruolo e giornata tipo
• Dieci clienti, un solo Sistemista: come si gestiscono le priorità in un Managed Service Provider