Progetta documenti come parte di Agile

"vague requirements, bad acceptance criteria, good luck!"

sì, questo è lo stesso tipo di requisiti che ottieni anche se provi a inchiodarli troppo! (Ad esempio, un documento di 10.000 requisiti che un cliente governativo impiegò 4 anni per creare era ancora pieno di incongruenze, vaghezze e persino affermazioni internamente contraddittorie: se 4 anni di documentazione dei requisiti non possono ottenere un requisito decente, esatto, fare pensi mai che sarai in grado di ottenere qualcosa di non vago?)

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

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

Alla fine ottieni esattamente ciò che il cliente desiderava, anche se non sapeva cosa fosse! (diavolo, loro mai sanno quello che vogliono, non esattamente).

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

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

In secondo luogo, ti consiglio vivamente di riconsiderare la produzione di documenti di progettazione dopo il lavoro preliminare sulle storie. Ci 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 penso che sia troppo presto.

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

1. Come team abbiamo bisogno di capire in che modo la storia influirà sul design.
2. Avere documenti di progettazione si è dimostrato utile quando nuovi membri (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 gli ingegneri di manutenzione che potrebbero dover risolvere il problema dopo il rilascio.

Per soddisfare (1) non è necessario produrre un documento di progettazione reale. La tua squadra dovrebbe avere ancora 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 richiederà ore (se non giorni) per scrivere solo per discutere i cambiamenti di progettazione.

(2) o (3) non sono necessari durante lo sviluppo della storia attuale e più che probabile che non saranno necessari per diverse iterazioni successive.

Ricorda inoltre che ogni volta che un membro del team sta scrivendo / aggiornando i documenti di progettazione, è il momento in cui il codice non viene scritto. Quando scrivi documenti prima del codice reale, c'è quasi il 100% di possibilità che essi debbano essere aggiornati perché una volta che si inizia a progettare il codice, finisce sempre per essere modificato. E anche se scrivi i documenti di progettazione dopo il codice, come il nostro team ha imparato, il refactoring delle storie successive modifica ancora il design.

Quindi cosa consiglierei:

1. Inizialmente produci modelli / modelli temporanei in modo che il tuo team possa avere una conversazione intelligente prima della codifica. Non aspettarti di mantenerli e non perdere tempo a formalizzarli.
2. Esegui la documentazione di progettazione ufficiale solo se qualcuno ne ha bisogno (vale a dire che il tuo team ha un reale bisogno di memoria organizzativa)
3. Produce solo la documentazione di progettazione sul codice che è stato stabilizzato. Non ha senso provare a documentare un modulo che continua a essere modificato in ogni iterazione.
4. Produce documenti di progettazione che descrivono completamente un modulo (o una parte del prodotto). In passato eravamo soliti scrivere documenti di progettazione che documentavano le modifiche che devono essere apportate. Quei documenti erano completamente inutili non appena il rilascio è stato fatto.
5. Mantiene il documento di livello molto alto. Se scrivi 20 pagine che coprono l'architettura e il design di alto livello, quel documento sarà a) 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 di specifiche dettagliate, quasi sempre non corrispondono alla realtà, è troppo per chiunque da leggere e alla fine dovrai mantenere e aggiornare 700 pagine invece di 20 ogni volta che vengono apportate modifiche future.

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

Il mantra Agile preferisce " Software di lavoro su documentazione completa ". Ma nota il bit in fondo al manifesto.

That is, while there is value in the items on the right, we value the items on the left more."

Uncle Bob ha una buona politica per la documentazione

Produce no document unless it's need is immediate and significant.

Hai ragione che alcune persone usano Agile come scusa per non produrre documentazione, ma è una cattiva Agile. Ignora i bit che ho evidenziato tra virgolette.

Tutto ciò che è stato detto, quando dici "al momento ci troviamo in una situazione in cui una nuova funzionalità può avere un impatto su più aree nel nostro sistema di" grande palla di fango ", se vuoi essere Agile, devi fare qualcosa questo.

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

es. Rendi il bisogno immediato e significativo.

La questione dell'agile è che gli sforzi della documentazione devono essere guidati dal team di scrum. Se gli sviluppatori non ritengono che la documentazione esterna sia sufficiente per le loro esigenze, la storia dell'utente 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 nel farne parte dei criteri di accettazione. Per questo motivo, ho effettivamente trovato la nostra documentazione più focalizzata ed efficace dal passaggio alla mischia.

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

Per un esempio che ha funzionato molto bene per noi, abbiamo dovuto testare una nuova scheda circuitale il più rapidamente possibile dopo la realizzazione del prototipo. Abbiamo creato due storie di utenti per tutto ciò che era necessario testare: uno per progettare il test e uno per eseguire il test. Un criterio di accettazione per la storia del design era che la procedura di test era completamente documentata nella storia di esecuzione.

Quando siamo arrivati alla parte di test, è andata più agevolmente di quanto non abbia mai visto. Abbiamo appena aperto la user story e seguito la procedura passo 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 di un chip che usiamo, al fine di rendere più facile per gli altri team raccoglierlo per i propri prodotti.

In sintesi, se ritieni che la tua documentazione sia sofferta, la soluzione è facile come creare una user story separata e / o renderla parte dei criteri di accettazione.

Quando parli di requisiti poveri, la prima cosa che mi viene in mente è assicurarsi di avere i criteri di test. Se possibile, creare alcuni casi di test automatici riutilizzabili per parti esistenti del sistema. Una volta che tutti si sentono a loro agio, passa alla scrittura dei casi di test prima che il codice venga scritto. I buoni test case possono fare molto per documentare i comportamenti di un sistema.

Per quanto riguarda i documenti di progettazione specifici da utilizzare, come altri hanno già detto, dipende in larga misura dalle esigenze della squadra 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 generare il codice dal documento. La manutenzione della documentazione può diventare piuttosto costosa, quindi scegli saggiamente quando si mantiene un documento di design.

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