Documentazione agile: equilibrio tra velocità e conservazione delle conoscenze

I vari documenti, manufatti e processi legati alla loro generazione sono alcuni dei principali simboli del modello Waterfall. Prendendo in prestito da Lean, Agile considera gran parte della documentazione come "rifiuti" che devono essere eliminati per ottimizzare il ciclo di vita dello sviluppo.

Per molti project manager, non è difficile capire come le fasi Waterfall si trasformino in sprint: lo stesso lavoro è compiuto; è solo organizzato in un modo diverso. Tuttavia, la rimozione della maggior parte della documentazione è una pillola più difficile da ingoiare in quanto sottolinea un modo di lavorare completamente diverso. Richiede allentare le redini del controllo, abbracciare l'ignoto e autorizzare il team di consegna a prendere decisioni sul posto.

L'approccio tradizionale alla documentazione viene messo in discussione

Nella metodologia Waterfall, viene dedicato molto tempo alla documentazione dei requisiti del progetto e alla definizione dei dettagli delle soluzioni. Questo processo funziona quando i requisiti sono completamente chiari e siamo certi che nulla cambierà rispetto a ciò che è stato catturato e delineato. Eppure le esperienze della maggior parte delle aziende negli ultimi decenni hanno dimostrato che questo non è quasi mai vero. Nel mondo di oggi, il ritmo del cambiamento è così dinamico che le esigenze del cliente cambiano notevolmente nel momento in cui completiamo la fase di documentazione.

L'obiettivo di Agile è quello di portare a termine le cose e aggiungere valore agli stakeholder. È costruito in modo tale che il modello scoraggi il lavoro sulle periferiche e su attività che non aggiungono direttamente e immediatamente valore al cliente.

Documentazione in Waterfall vs. Agile

Ogni azienda ha un diverso livello di documentazione, che può differire anche a livello di progetto. Ma ecco come appaiono le tipiche procedure di documentazione nei progetti Waterfall e Agile:

Il caso della documentazione

Waterfall promuove un approccio molto più rigoroso alla documentazione, che potrebbe sembrare eccessivo. Ma prima di liquidare questo come "rifiuto", ecco alcuni vantaggi derivanti dall'avere solide procedure di documentazione.

Opportunità di pensiero strategico

Chi non pianifica, pianifica di fallire. La documentazione costringe un project manager a sedersi e riflettere sulle cose, quindi trovare le soluzioni migliori. Le persone a volte interpretano erroneamente il valore Agile del software funzionante rispetto a una documentazione completa nel senso che non è necessaria alcuna documentazione. Quindi si precipitano al mercato, una mossa che Paul Adams, vicepresidente del prodotto presso Intercom, descrive come lanciare oggetti contro il muro e vedere cosa si attacca. Progettare soluzioni, creare piani, deliberare azioni: queste attività creano valore risparmiando tempo nel non sviluppare ogni singola idea di funzionalità che viene in mente.

UX e coerenza funzionale

Man mano che le aziende crescono da pochi fondatori a centinaia o migliaia di dipendenti, molti team diversi iniziano a lavorare sugli stessi prodotti o su prodotti correlati. Il team A potrebbe pensare che ciò su cui stanno lavorando non è correlato a ciò su cui sta lavorando il team B, ma per l'utente finale è tutto lo stesso prodotto. Invece di team interfunzionali che fanno le proprie cose, una documentazione chiara sull'esperienza utente e sui livelli funzionali evita un flusso utente disgiunto.

La documentazione può essere convertita in guide per l'utente

In Waterfall, molto tempo viene dedicato alla descrizione delle soluzioni e al modo in cui verranno utilizzate. Le immagini di progetti ad alta fedeltà vengono create per gli sviluppatori front-end. Tutte queste risorse richiedono meno lavoro per essere convertite in guide per l'utente interne o esterne rispetto alla loro creazione da zero.

In che modo Agile riduce le esigenze di documentazione

Un fattore che si presenta ripetutamente come scusa per imporre la documentazione è il turnover dei dipendenti. I manager temono di perdere le conoscenze istituzionali quando le persone se ne vanno e ne si uniscono di nuove per sostituirle. Come faranno a sapere cosa è stato implementato e come funziona? Quanto tempo impiegheranno a recuperare? Il team attuale avrà la larghezza di banda per tenere in mano i nuovi membri del team?

La speranza è che una buona documentazione metta rapidamente al passo i nuovi dipendenti che lavorano per lo più in modo indipendente. Tuttavia, Agile riduce intrinsecamente la necessità di documentazione attraverso tecniche di collaborazione che, allo stesso tempo, riducono i tempi di onboarding. Ecco alcuni modi in cui Agile riduce la necessità di documentazione.

Interazione regolare tra team di prodotto e membri del team Agile

Il Manifesto Agile promuove "individui e interazioni su processi e strumenti". Poiché i requisiti tendono a cambiare durante un progetto e nascono nuove idee, Agile garantisce il chiarimento dei requisiti direttamente dalla fonte invece di dipendere da artefatti scritti che necessitano di un aggiornamento costante.

Toelettatura e pianificazione compartimentalizzano le attività

La preparazione del backlog e la pianificazione dello sprint suddividono le funzionalità in parti specifiche e implementabili che sono facilmente comprensibili e su cui è possibile lavorare in modo indipendente. Ciò crea un'opportunità per i nuovi assunti di essere produttivi all'inizio, pur non comprendendo ancora appieno il quadro generale dell'intero progetto.

Le storie degli utenti forniscono una documentazione efficiente

Il semplice formato delle storie degli utenti consente ai project manager di acquisire i requisiti minimi che creano una comprensione condivisa tra tutti i membri del team. Anche se una user story non diventa uno sprint, lo spreco di creare questo artefatto di documentazione è molto basso. Man mano che le storie degli utenti si trasformano in sprint, possono essere arricchite e integrate con altre informazioni richieste come wireframe, progetti, criteri di accettazione, ecc. Questo processo fornisce una consegna della documentazione molto efficiente, altamente usa e getta e prodotta nelle fasi di sviluppo più appropriate.

Necessità ridotta di documentazione del codice

Tecniche come la programmazione a coppie e la revisione del codice creano opportunità costanti per diffondere la conoscenza tecnica in tutto il team, in particolare tra i nuovi membri del team. Il feedback costante porta a una comprensione condivisa che ha anche la flessibilità di adattarsi a nuove circostanze invece di diventare rapidamente obsoleta in un documento da qualche parte.

Cerimonie agili

Standup giornalieri, revisioni di sprint e retrospettive creano ampie opportunità per risolvere problemi e prendere decisioni faccia a faccia invece di fare affidamento su e-mail e documenti. Il periodo di tempo limitato di tutte le cerimonie garantisce che solo le informazioni più importanti abbiano la priorità invece di perdere tempo a documentare tutto, anche se è probabile che non vengano mai utilizzate.

Tutto quanto sopra riduce, direttamente o indirettamente, la documentazione e dà la priorità alla realizzazione degli obiettivi del progetto, assicurando che nulla vada davvero perso a causa della mancanza di documentazione.

Approcci ibridi alla documentazione

Alcune aziende preferiscono ancora avere della documentazione, anche in un ambiente Agile. Agile non è prescrittivo, perché ogni progetto è diverso e ha un insieme unico di circostanze che devono essere affrontate.

Di seguito sono riportati alcuni esempi di come Agile può essere combinato con metodi di documentazione più dispendiosi in termini di tempo.

Combinando UML e Agile

Prendi in considerazione l'utilizzo di un linguaggio di modellazione standard come Unified Modeling Language (UML), che è molto strutturato e ha entità definite per visualizzare un sistema. Questo aiuta a mantenere il contenuto molto semplice e focalizzato su ciò che è necessario e garantisce un uso minimo della lingua scritta. Strumenti come StarUML e Draw.io, tra molti altri, sono opzioni convenienti.

Generatori di documentazione del codice

Un altro approccio è garantire che il codice sia molto più leggibile introducendo commenti più strutturati e dettagliati come parte dei dettagli della classe, dei dettagli del metodo, dell'utilizzo dei parametri, delle dipendenze e così via. Esistono molti strumenti che automatizzano il processo di generazione di documenti utili dal codice sorgente e sono chiamati generatori di documentazione. Vanno da quelli generici a quelli specifici del linguaggio di programmazione.

Design dettagliato e documenti UX

La definizione dei requisiti utilizzando wireframe, mockup, diagrammi di flusso utente, diagrammi di sequenza, ecc. aiuta a semplificare i flussi di progetto e a chiarire esplicitamente al team tecnico ciò che deve essere sviluppato. I documenti di progettazione sono un ottimo modo per avere un livello variabile di documentazione più rigida. Esistono vari strumenti di wireframing e UX tra cui scegliere per queste attività.

Gli strumenti di gestione del progetto automatizzano la documentazione

Una gestione dei progetti più potente e strumenti correlati come JIRA, Confluence, Asana e Basecamp forniscono un modo per conservare tutte le informazioni relative al progetto in un unico posto. Le attività possono essere collegate, taggate, nidificate e assegnate a diversi membri del team, che possono quindi lasciare commenti e segnalare eventuali problemi. Tutte queste azioni, insieme alla flessibilità di adattare tali strumenti, possono creare una notevole quantità di documentazione con uno sforzo minimo o nullo.

Inoltre, storicamente, parte delle esigenze di documentazione derivano da obblighi di rendicontazione. Le parti interessate desiderano accedere alle prestazioni del team o ad altre metriche pertinenti. Gli strumenti di gestione dei progetti semplificano l'automazione di dashboard e viste personalizzate che riflettono l'avanzamento del progetto e si collegano alla documentazione pertinente all'interno dello strumento.

La gestione della documentazione è un atto di bilanciamento

I creatori del Manifesto Agile scrivono che apprezzano "il software funzionante rispetto alla documentazione completa". Tuttavia, aggiungono anche un disclaimer che "mentre c'è valore negli articoli a destra, [essi] apprezzano di più gli articoli a sinistra". Agile non suggerisce di rimuovere tutta la documentazione, perché parte della documentazione ovviamente fornisce valore; suggerisce semplicemente che la priorità dovrebbe essere sul software funzionante e sull'aggiunta della documentazione solo se necessario a seconda delle circostanze del progetto e senza ostacolare pesantemente il progresso dello sviluppo.

I project manager devono raggiungere un equilibrio tra dedicare meno tempo alla documentazione e dedicare più tempo alla fornitura di software funzionante e capire effettivamente dove una qualche forma di documentazione è necessaria per il successo a lungo termine.