Come bilanciare i requisiti della documentazione con gli sviluppi Agile [duplicato]

Non direi necessariamente che agile evita la documentazione tanto quanto evita la documentazione up-front . Lo scopo è quello di affrontare il problema che ciò che viene documentato con un così grande sforzo in avanti (a) finisce per essere molto diverso da ciò che viene creato perché le esigenze aziendali cambiano, si insinua, ecc. O (b) fa fallire il progetto perché la consegna dipende da aspettative così grandi.

Ci sono certamente casi in cui la documentazione è essenziale. Ho appena iniziato a lavorare su un'applicazione commerciale, per la quale è essenziale fornire documentazione accurata e aggiornata ai clienti. Anche la squadra è agile (mischia).

Nel nostro caso, abbiamo una persona (non dev) che è responsabile della documentazione.

Questo aiuta, ma ci sono più componenti critici. Uno è che rende la documentazione parte della "definizione di fatto". ottieni i criteri di accettazione dagli stakeholder per ogni funzione, ma aggiungi il requisito che la funzionalità sia documentata. Il secondo componente è che inserisci la documentazione nel tuo processo . Non può essere opzionale, non può accadere "ogni volta". Nel nostro caso, dimostriamo una determinata funzionalità per la persona della documentazione dopo la revisione delle parti interessate e prima che vada a QA / Test. Ogni volta. Se hai detto che il tuo articolo del backlog è pronto per il test e non lo hai inviato per la documentazione, hai interrotto il processo - qualcosa come rompere la compilazione.

Questo si adatta meglio con agile perché sei solo a documentare ciò che è effettivamente nel prodotto finito.

Mi rendo conto che stiamo parlando di diversi tipi di documentazione: parli di più sulle specifiche. L'ultima parte vale ancora: documenta solo ciò che hai effettivamente inserito nel prodotto. Aggiungerò anche a questo il suggerimento che puoi creare i tuoi test unitari come "specifiche eseguibili" e lasciare che la tua suite di test documentino il prodotto. Non devi necessariamente praticare TDD per raggiungere questo obiettivo, ma se la tua squadra non è già in grado di effettuare test unitari, allora questa è tutta un'altra palla di cera.

In primo luogo, stai attento ad affidarti ad Agile senza esperienza è il modo migliore per fallire. Non vuoi migrare a un'esperienza agile senza una squadra che sappia cos'è agile e come dovrebbe funzionare. Suggerisco caldamente, prima di passare all'agile trovare almeno una cintura nera, e inviare più della metà della tua squadra ad un allenamento agile.

Con ciò detto, agile non dice NESSUNA documentazione. Si afferma solo che il processo di agile, riduce la necessità di una documentazione estesa. Poiché esiste un ciclo di feedback più stretto, gli utenti finali generalmente capiscono cosa dovrebbe fare il sistema. La maggior parte dei progetti agili di successo su cui ho lavorato è stata un qualche tipo di wiki / strumento di collaborazione che è stata la vera documentazione live. Gli sviluppatori / gli utenti aziendali hanno tutti contribuito attivamente a documentare il sistema e chi può dire che è possibile aggiungere ai propri articoli qualche tipo di panoramica del sistema.

Dalla mia esperienza passata, i manuali di 40 pagine non sono mai utili o sono utili solo per le persone super tecniche. Quando stai sprecando le tue ultime 3 settimane di scrittura della documentazione, ti mancano settimane preziose di periodi di transizione. Il tempo è meglio speso nel mentoring degli altri, guidandoli attraverso il codice live, aiutandoli a supportare, ecc.

Per quanto riguarda il punto finale, agile non afferma di progettare prima dei requisiti, dice semplicemente che non devi fare TUTTI i tuoi requisiti prima di iniziare la progettazione.

Speriamo che risponda alla tua domanda.

Personalmente, insisto per un giorno e mezzo ogni settimana come giornata di documentazione (in genere venerdì). Mentre le nuove classi / metodi / proprietà dovrebbero essere docblocked durante lo sviluppo, quella mezza giornata in più consente annotazioni nei documenti API e commenti nel codice. Ogni gruppo di nuovi commenti viene sottoposto a peer review per garantire che un altro membro del team possa comprendere tale documentazione, prima che lo sviluppo del codice possa continuare.

Ho trovato, in particolare quando si estendono metodi con nuovi argomenti, che spesso questi non vengono aggiunti ai docblock, quindi l'API diventa rapidamente obsoleta ... ma questo 1/2 giorno cerca di imporre di mantenerlo aggiornato.

Ho anche cercato di automatizzare i processi per identificare quando il docblock non è più sincronizzato con la definizione del metodo.

Quindi 1 giorno in ogni mese è dedicato a garantire che la documentazione non API sia mantenuta ... ad es. esempi di lavoro, ecc.

Se questi giorni "generali" sono effettivamente pianificati nello sprint, la documentazione cessa di essere un grosso problema.

Lascia che ti chieda questo. Sotto cascata quante volte hai scritto un documento di disegno di 40 pagine e quando il progetto è stato "superato", a cosa avevi abbinato quel documento? Quanto tempo hai speso per quel documento? Quante persone lo hanno effettivamente usato? Quante specifiche di progettazione di 40 pagine hai mai trovato davvero utili?

In agile non perdiamo tempo a spendere settimane a scrivere documenti di design quando potremmo scrivere codice e consegnarlo. Non stiamo dicendo che le tue API dovrebbero essere un mistero, o non dovresti chiarire che cosa dovrebbe fare il codice. Al contrario, dedichiamo uno sforzo ulteriore al design delle API. Assicurandosi che i metodi abbiano un buon nome. Che lo scopo di una lezione è chiaro. Che il codice è pulito e ovvio.

Normalmente, trovo che l'ultima cosa che i consumatori del mio codice vogliono sia un documento di progettazione grossa. Quello che vogliono sono bei set di codice di esempio e usi ovvi ben disegnati. Perché è quello che vorrei.

AGGIORNAMENTO: Vorrei anche sottolineare che la maggior parte dei negozi Agile tende a documentare il proprio codice con una serie di test di accettazione in qualcosa come Fitnesse o Cucumber. Ciò consente all'API di essere documentata con un codice funzionante che la esercita costantemente in un ambiente CI. In questo modo la tua documentazione non diventerà mai obsoleta, perché se così fosse, sarebbe rotta.

Il Manifesto Agile si conclude con la frase "Cioè, mentre c'è valore negli articoli a destra, valutiamo di più gli articoli a sinistra". Significato: in dubbio decide di lavorare con il software sulla documentazione. Ma come hai detto, c'è bisogno di documentazione nella tua situazione, senza dubbio a riguardo. Agile è spesso (err-) inteso come "dovresti ridurre lo sforzo sugli oggetti a destra, altrimenti non sei agile".

Devi sempre evitare la documentazione non necessaria. Concordato. Ma: dovresti passare un po 'di tempo a pensare a quale documentazione è necessaria, e quale no. Non lasciatevi ingannare da una prospettiva ristretta basata sui ruoli, come ad es. un programmatore. Il programmatore potrebbe non aver bisogno di un documento che descriva la sua architettura. Ma questo non significa che sia un documento non necessario per il ciclo di vita del progetto. Ommitting potrebbe metterti in una situazione altamente non agile in pochi mesi.