Progettare documenti come parte di Agile

Nel mio posto di lavoro, affrontiamo una sfida in quanto "agile" troppo spesso ha significato "requisiti vaghi, criteri di cattiva accettazione, buona fortuna!" Stiamo cercando di affrontarlo, come uno sforzo di miglioramento generale.

Quindi, come parte di ciò, sto proponendo di generare documenti di progettazione che, al di là del livello della storia dell'utente, riflettano accuratamente il risultato di indagini preliminari sull'effetto di una determinata funzionalità all'interno del sistema e includendo le risposte alle domande che abbiamo chiese l'azienda.

Esiste uno standard efficace per questo?

Attualmente ci troviamo di fronte a una situazione in cui una nuova funzionalità potrebbe avere un impatto su più aree del nostro sistema "big ball of mud" e le stime stanno iniziando a salire a causa di questo debito tecnico. Speriamo che processi di progettazione più ponderati possano aiutare.

"requisiti vaghi, criteri di cattiva accettazione, buona fortuna!"

sì, questo è lo stesso tipo di requisiti che ottieni anche se provi a inchiodarli anche tu! (ad esempio, un documento di 10.000 requisiti che ha richiesto a un cliente governativo 4 anni per essere creato era ancora pieno di incoerenze, vaghezza e persino dichiarazioni contraddittorie internamente. Se 4 anni di documentazione sui requisiti non può fornirti un requisito decente, esatto, hai mai pensato di riuscire a ottenere qualcosa di non vago?)

Quindi ... il modo agile è stato inventato per capire che questo succede e per lavorare con esso piuttosto che provare a lavorare contro di esso.

Si inizia chiedendo "cosa vuoi" e il cliente risponde con "qualcosa del genere". Fai un po 'di lavoro e poi torni dal cliente e dici "è come quello che volevi?", E il cliente di solito dice "sì ma ..." dopodiché chiedi "cosa vuoi".

Alla fine ottieni esattamente ciò che il cliente voleva, anche se non sanno cosa sia! (diavolo, non sanno mai cosa vogliono, non esattamente).

Nel nostro team, da quando siamo diventati agili, abbiamo anche cercato di restringere e capire quanta documentazione sia effettivamente richiesta. Posso condividere con te ciò che abbiamo imparato fino ad ora.

Prima di ogni altra cosa, assicurati di leggere questo articolo sulla documentazione Agile / Lean . Ottima lettura

In secondo luogo, ti consiglio caldamente di riconsiderare la produzione di documenti di progettazione dopo un lavoro preliminare sulle storie. L'abbiamo provato prima e si è dimostrato uno spreco. Nel mezzo dell'ultima versione abbiamo deciso di aggiornare i documenti di progettazione SOLO DOPO che il codice per la storia è stato consegnato. E ora sto pensando anche che è troppo presto.

Devi chiederti perché vuoi fare documenti di progettazione prima della codifica. Per noi questi erano i motivi:

1. Come team dobbiamo capire come la storia influenzerà il design.
2. Avere documenti di progettazione si è rivelato utile quando i membri nuovi (o temporanei) si uniscono al team o quando ritornano al codice su cui nessuno ha lavorato per oltre un anno. Quindi sono utili per la memoria organizzativa per aiutare a capire come funziona il codice.
3. I documenti di progettazione sono utili per i tecnici della manutenzione che potrebbero dover risolvere il codice dopo il rilascio.

Per soddisfare (1) non è necessario produrre un vero documento di progettazione. Il tuo team dovrebbe comunque avere una fase di progettazione prima della codifica, ma quella fase può essere semplice come una sessione di 15 minuti davanti a una lavagna o un tovagliolo. Non è necessario produrre un documento effettivo che impiegherà ore (se non giorni) per scrivere solo per discutere delle modifiche al progetto.

(2) o (3) non sono necessari durante lo sviluppo della storia attuale e molto probabilmente non saranno necessari per diverse iterazioni successive.

Inoltre, tieni presente che ogni volta che un membro del team sta scrivendo / aggiornando documenti di progettazione, è il momento in cui il codice non viene scritto. Quando scrivi documenti prima del codice effettivo, c'è quasi il 100% di probabilità che richiedano l'aggiornamento perché una volta che inizi la progettazione del codice finisce sempre per essere modificato. E anche se scrivi documenti di progettazione dopo il codice, come il nostro team ha imparato, il refactoring delle storie successive altera ancora il design.

Quindi cosa consiglierei:

1. Inizialmente produce abbastanza progetti / modelli temporanei in modo che il tuo team possa avere una conversazione intelligente prima della codifica. Non aspettarti di conservarli e non perdere tempo a formalizzarli.
2. Produrre la documentazione ufficiale di progettazione solo se qualcuno ne avrà bisogno (ad esempio, il tuo team ha un reale bisogno di memoria organizzativa)
3. Produrre solo documentazione di progettazione su codice stabilizzato. Non ha senso cercare di documentare un modulo che continua a essere modificato in ogni iterazione.
4. Produrre documenti di progettazione che descrivono appieno un modulo (o parte del prodotto). In passato scrivevamo documenti di progettazione che documentavano le modifiche da apportare. Quei documenti erano completamente privi di valore non appena il rilascio è stato fatto.
5. Mantieni il documento di altissimo livello. Se scrivi 20 pagine che trattano di architettura e design di alto livello, quel documento a) sarà effettivamente letto da altre persone eb) aiuterà le persone a familiarizzare con il layout generale del tuo codice. Per i dettagli le persone possono andare direttamente nel codice. Se scrivi 700 pagine con specifiche dettagliate, quasi sempre non corrisponderanno alla realtà, è troppo difficile da leggere per chiunque e finirai per mantenere e aggiornare 700 pagine invece di 20 ogni volta che verranno apportate modifiche future.

Il "mantra" Agile non deve fare a meno della documentazione.

Il mantra Agile è preferire " Software di lavoro piuttosto che documentazione completa ". Ma nota la parte in fondo al manifesto.

Cioè, mentre c'è valore negli articoli a destra , apprezziamo di più gli oggetti a sinistra. "

Lo zio Bob ha una buona politica per la documentazione

Non produrre documenti a meno che non sia immediato e significativo .

Hai ragione sul fatto che alcune persone usano Agile come scusa per non produrre documentazione, ma questa è cattiva Agile. Sta ignorando i bit che ho evidenziato nelle citazioni sopra.

Detto questo, quando dici "attualmente stiamo affrontando una situazione in cui una nuova funzionalità potrebbe avere un impatto su più aree del nostro sistema" big ball of mud ", se vuoi essere Agile, devi fare qualcosa al riguardo.

Quando hai la tua documentazione, usala per modulare il tuo codice. In questo modo rimuovi la necessità a lungo termine di conservare la documentazione (cosa che non accadrà) rimuovendo la necessità a lungo termine della documentazione.

vale a dire. Rendi il bisogno immediato e significativo.

La cosa agile è che gli sforzi di documentazione devono essere guidati dal team di scrum. Se gli sviluppatori non ritengono che la documentazione esterna sia sufficiente per le loro esigenze, la user story viene bloccata fino a quando non lo fanno. Se l'azienda ritiene che gli sviluppatori non stiano producendo una documentazione adeguata, il proprietario del prodotto insiste per renderlo parte dei criteri di accettazione. Per questo motivo, ho trovato la nostra documentazione più focalizzata ed efficace da quando sono passato alla mischia.

Usiamo VersionOne per tracciare le storie degli utenti, ma sono sicuro che i nostri metodi si applicano ad altri sistemi. Ti consente di allegare file alle storie degli utenti. Abbiamo scoperto che è un posto estremamente utile per mettere documenti di progettazione.

Per un esempio che ha funzionato davvero bene per noi, abbiamo avuto la necessità di testare un nuovo design del circuito il più rapidamente possibile dopo la realizzazione del prototipo. Abbiamo creato due user story per tutto ciò che necessitava di test: uno per progettare il test e uno per eseguire il test. Un criterio di accettazione per la storia del progetto era che la procedura di prova era completamente documentata nella storia dell'esecuzione.

Quando siamo arrivati ​​alla parte di test, è andata più agevolmente di quanto abbia mai visto. Abbiamo appena aperto la user story e seguito la procedura passo dopo passo. La documentazione era esattamente ciò di cui avevamo bisogno per completare la storia, né più né meno.

Abbiamo un'altra storia nel nostro backlog solo per migliorare la documentazione per un chip che utilizziamo, al fine di rendere più facile per altri team raccoglierlo per i propri prodotti.

In sintesi, se ritieni che la tua documentazione stia soffrendo, la soluzione è semplice come creare una storia utente separata per essa e / o renderla parte dei criteri di accettazione.

Quando parli di requisiti scadenti, la prima cosa che mi viene in mente è assicurarti di avere i criteri di prova. Se possibile, creare alcuni casi di test automatizzati riutilizzabili per le parti esistenti del sistema. Una volta che tutti si sentono a proprio agio con ciò, passa alla scrittura dei casi di test prima che il codice venga scritto. Buoni casi di test possono fare molto per documentare i comportamenti di un sistema.

Per quanto riguarda quali specifici documenti di progettazione utilizzare, come altri hanno già detto, è fortemente dipendente dalle esigenze del team e da quale sarà il prossimo compito che intraprenderanno. Quando possibile, prova a utilizzare strumenti in grado di generare i documenti (dal codice) che utilizzeresti o di generare il codice dal documento. La manutenzione della documentazione può diventare piuttosto costosa, quindi scegli saggiamente quando persisti un documento di progettazione.

Personalmente ho avuto un buon successo con i diagrammi di classe generati da casi di test di codice e fitness. Il team stampa un paio di diagrammi di classe, fa una sessione di markup con il proprietario del prodotto e quindi formula un preventivo da lì. Per quanto riguarda il fitness, ho la fortuna di lavorare con un paio di proprietari di prodotti che sono molto bravi a esprimere ciò che vogliono nei fogli di calcolo, che vengono poi convertiti in tabelle per il fitness.