Il valore di una specifica aggiornata

Dipende.

Mantenere la specifica aggiornata durante lo sviluppo ha molti vantaggi, tra cui:

• implementatori, tester di usabilità, QE, doc, ecc. sanno sempre dove andare per il design attuale concordato
• gli osservatori esterni (ad esempio i responsabili o gli stakeholder) possono vedere cosa intendi fare
• il team ha qualcosa da guardare indietro per capire se le cose sono cambiate durante l'implementazione. Ovviamente ciò richiede una specifica controllata dalla versione.
• soprattutto, ti costringe a annotare cose. Il processo di scrivere le cose rivela molte ipotesi nascoste.

Ma non tutti i cambiamenti devono riflettersi nelle specifiche. Proprio come il livello di dettaglio da inserire nelle specifiche, alcune cose sono troppo piccole. Questo è un giudizio, e la squadra dovrà accontentarsi di una pratica qui.

L'aggiornamento delle specifiche è anche un lavoro extra, ovviamente, quindi è importante assicurarsi che il lavoro extra stia aggiungendo valore. Se ti trovi regolarmente ad aggiornare le specifiche senza che nessuno usi il risultato, allora questo è un flag di avviso (e potrebbe significare cambiare le pratiche del tuo team piuttosto che non tenerti aggiornato sugli aggiornamenti delle specifiche).

Più lungo è il progetto, più è importante aggiornare le specifiche. Funzione di un'ora? Probabilmente può farla franca solo implementandola. Una settimana? Aggiorna le specifiche di volta in volta. Un mese? Sicuramente vale la pena di fare il check-in più volte.

Infine, più grande è la squadra, più è prezioso avere una specifica scritta. MA - i team più grandi hanno un tempo più difficile per mantenere il contesto, quindi le specifiche potrebbero non essere in grado di resistere a tutti: potrebbero essere interpretati erroneamente da persone che non capiscono cosa significhi. Quindi è solo un pezzo del puzzle.

Credo che la cosa più importante che una specifica "implementata" dovrebbe coprire sono le ragioni delle decisioni che hai preso. Tutto il resto dovrebbe essere ovvio dal codice e dai test (spero che metà di quei 60K LOC siano test!). In altre parole, il "cosa" e "come" sono già espressi nel codice, che è il "documento" più aggiornato che esiste.

Le persone che leggono il tuo codice più tardi (incluso te) si chiederanno "perché" hai fatto le cose in un certo modo e questo non è qualcosa a cui il codice o i test possono rispondere. Domande dal basso livello "perché hai usato un LinkedList invece di un ArrayList" al livello alto "perché hai usato il framework X invece di Y o Z?" sono importanti da discutere in un documento che viene scritto dopo aver implementato le cose nel codice. Non c'è niente di peggio che incontrare un codice che fa le cose in un certo modo, cambiandolo in qualche altro meccanismo, e scoprire il tuo nuovo modo non funziona e allora scoprire che il tuo "nuovo" modo aveva già stato provato e scartato! Se solo qualcuno ti avesse detto ...

Per quanto spesso dovrebbe essere aggiornato, la mia regola pratica è ogni volta che viene presa una decisione non banale. Se aspetti di aver terminato una funzione o parte di una funzione, probabilmente dimenticherai alcune delle sfumature che sono state prese nella tua decisione di fare le cose in un certo modo.

Iniziamo con il processo mediante il quale stimerai quanto tempo ci vuole per fare il tuo lavoro. Valuta sempre il tempo per la documentazione, le riunioni e le comunicazioni via email. Ora per i progetti futuri non rimarrai senza tempo per fare quelle cose. Supponiamo anche solo 6 ore al giorno a persona quando si calcola la data di fine per la consegna (c'è sempre un lavoro indiretto come ad esempio riunioni e ferie necessarie, ecc., Per cui non si può mai pianificare per nessuno un progetto 40 ore una settimana o perderai ogni scadenza e non avrai mai tempo per fare documentazione). Questi sono i due motivi più comuni per cui ho visto le persone a corto di tempo.

A mio parere, ciò che è fondamentale per te per aggiornare su questo ultimo progetto sono i bug che hai risolto che non soddisfacevano le specifiche. Personalmente il tuo manager non ci è riuscito perché non avrebbe mai dovuto permettere che ciò accadesse, in particolare se i clienti (e anche gli utenti interni erano clienti) non erano stati informati in anticipo. Ci può essere una buona ragione dal punto di vista dell'utente per quel requisito che hai buttato fuori perché è stato più facile correggere il bug se hai ignorato il requisito. Ora possono aspettarsi comportamenti che non otterranno. Questo è un fallimento del tuo intero staff di sviluppo che consente a tali azioni di accadere.

Una ragione per cui è necessario un aggiornamento è per la manutenzione. Prima o poi qualcuno arriverà per aggiustare qualcosa che è stato cambiato senza documentazione e penserà che il mancato rispetto delle specifiche è stato un bug, non un'azione deliberata e lo cambierà per seguire le specifiche.

O gli utenti si lamenteranno che non fa X che era nella specifica e non avrai alcuna prova che X sia stato cambiato perché il bug Y ha causato la rivalutazione di X come requisito. Essendo stato in alcuni di questi argumnenti in passato, posso dire che non sono belli se sono clienti interni o esterni. Minore è l'accordo che hai ricevuto per questi cambiamenti prima di eseguirli, più è probabile che si rialzino e mordi il personale di sviluppo in seguito. E tra sei mesi non ricorderai perché l'hai fatto in quel modo. Non è divertente spiegare perché hai fatto qualcosa quando non hai idea del motivo per cui l'hai fatto.

Le funzionalità aggiuntive non sono così importanti, ma probabilmente dovrebbero essere elencate almeno anche se non si ha il tempo di fare una descrizione completa.

Ora devi apportare queste modifiche quando sono fresche. Convinci il tuo manager a lasciarti trascorrere un giorno o anche mezza giornata facendo questo. Oppure sgattaiolare in una mezz'ora ogni giorno per le prossime due settimane, se necessario, per documentare le deviazioni più critiche.

Bugs were discovered and fixed in ways that don't correspond well with the spec

Additional needs were discovered and dealt with

We found areas where the spec hadn't thought far enough ahead and had to change some implementation

Tutti questi casi avrebbero dovuto innescare una richiesta di informazioni (RFI) al consulente / cliente e nessun lavoro avrebbe dovuto essere svolto fino a quando non fosse stata restituita una specifica modificata.

What value is there in keeping an updated spec?

How often should the spec be updated? With every change made that might affect it, just at the end of development, or something in between?

Copertura sul retro

Se le modifiche sono state apportate al software senza alcuna modifica alle specifiche, al momento della consegna del progetto ora sei aperto al cliente che indica "questo progetto non è conforme alle specifiche" (questo è successo a almeno un progetto in cui sono stato - per fortuna, abbiamo avuto le RFI e cambiamo i documenti per discutere il punto). Devi avere la traccia cartacea per sostenere il tuo cambiamento.

Avere un chiaro processo di cambiamento aiuta in altri modi - un progetto (non un software) con cui ero coinvolto se il cliente si lamentava quando il suo sistema era rotto. Abbiamo effettivamente estratto le specifiche e le (numerose) RFI documentate che hanno mostrato chiaramente che abbiamo considerato le specifiche di cui necessitare un emendamento, e le risposte del cliente che diceva "fallo come abbiamo detto". Il cliente ha finito per dover pagare il progetto originale e poi un secondo progetto per correggere i problemi originali (basti dire che non hanno ignorato le RFI la seconda volta).

Modifiche ai costi

C'è un ultimo vantaggio nella revisione e nell'aggiornamento continuo delle specifiche: alcune modifiche incideranno in modo significativo sullo sviluppo. Ciò significa che potrebbe esserci un costo aggiuntivo a carico del cliente (che era la motivazione per il cliente sopra menzionato che ignorava le RFI). Poiché la cronologia del progetto e il prezzo originari erano basati sulle specifiche originali, l'esecuzione di un processo di modifica assicurerà che il cliente sia consapevole dell'aumento dei tempi e del prezzo necessari per varie modifiche.

Solo un aspetto legale: mai.

Quando la specifica è parte di un contratto, non devi mai cambiare la specifica. Vorrei aggiungere note, addendum o cambiare documento o qualcosa di simile.

Alla fine puoi definire una specifica rivista. Il cliente deve dare l'ok durante la procedura di accettazione.