Processi: documentando la modifica delle specifiche

Devi davvero "aggiornare la wiki solo quando le decisioni vengono prese". Interruzioni e pressione del tempo NON sono una scusa.

Dopo tutto, hai bisogno di sviluppare casi di test, giusto? E dovrai eseguire questi test su ogni piattaforma, giusto? Bene, su cosa dovrebbero basarsi i test? Esatto, quelle decisioni che non stai documentando. Documentali, i tuoi test miglioreranno (e più facilmente), i tuoi prodotti avranno una qualità superiore e tutti sono contenti.

Il problema più grande con la conservazione della documentazione per il codice in una wiki è che i wiki non sono neanche lontanamente altrettanto flessibili quando si parla di controllo della versione.

Questa è una delle ragioni per cui mi piace mantenere la documentazione il più vicino possibile al codice, usando un sistema di documentazione diff friendly come rst e memorizza il codice nel repository del progetto insieme al codice.

Ho distillato molti dei miei pensieri sulla documentazione in una risposta alla domanda Quali sono i buoni modi per documentare il software scientifico? ma funzionano anche per codice aziendale come per codice scientifico.

Il mio terzo punto sulla documentazione di livello superiore è il più direttamente rilevante, ma non dimenticare che una volta che un progetto è completo, i test di unità probabilmente documentano i tuoi requisiti come implementati molto meglio dei tuoi documenti spec. meglio specificare i cambiamenti futuri in termini di ciò che hai già rispetto a quello che volevi originariamente.

Se scrivi la tua specifica come documento nel tuo repository del codice progetto, se diramazioni del tuo codice per una nuova versione, ottieni anche una parte della documentazione. Nel tuo caso, avvieresti un nuovo ramo dello sviluppo del codice, aggiornerai le specifiche, quindi aggiornerai il codice.

Per lo sviluppatore fare tutto questo sarebbe in sincronia e nessun altro vedrebbe le modifiche delle specifiche fino a quando non saranno pronte per incorporarle.

Una volta terminato il lavoro (o almeno raggiunto un livello distribuibile) le modifiche alle specifiche sarebbero state unite con (porting) negli altri progetti insieme al codice che implementa tali modifiche specifiche.

La cosa interessante è che l'atto di fusione genererà anche conflitti di unione se li hai, proprio come farebbe il codice. In questo modo puoi scoprire se due sviluppatori hanno cambiato le specifiche in modi che sono reciprocamente incompatibili.

"The problem we have is that there's no real procedure for making sure the decisions made
 in step 2 actually get documented"

Penso che tu abbia isolato il passaggio del tuo processo che puoi migliorare. Senza entrare nella modifica dell'intera struttura organizzativa, penso che qualcuno debba essere incaricato di mantenere le specifiche man mano che evolve. So che è ovvio, ma sarà il modo più semplice per ottenere ciò contro cui ti trovi. L'introduzione di un nuovo sistema avrà un sovraccarico iniziale, "Cambiare" il modo in cui le cose faranno probabilmente arrufferanno più piume di qualsiasi altra cosa.

Ehi, perché non assegnarlo al nuovo ragazzo (il FNG) !! LOL !!

buona fortuna!

Questo non ha nulla a che fare con la tua situazione speciale di "piattaforme multiple". Altri hanno lo stesso problema con una sola piattaforma. Da un punto di vista generale, vedo due approcci per affrontare questa situazione:

a) Aumenta il lavoro iniziale nel passaggio 1. Cerca di non fare solo una specifica funzionale, ma anche di specificare i requisiti non funzionali.

b) Evitare di dover scrivere documentazione evitabile nel passaggio 2. Meglio insegnare al proprio team come scrivere codice di auto-documentazione. Poi ci sono meno scuse come "non abbiamo il tempo per la documentazione". Certo, qualcuno dovrebbe aggiornare la tua Wiki anche nel passaggio 2, ma solo per documentare le decisioni ad alto livello. Quelle sono spesso solo una piccola parte delle cose da fare a livello di codice.

Ecco due link agli articoli di Joel Spolsky che potrebbero interessarti:

link

link

Utilizza lo sviluppo basato su test! In particolare, automatizza i test di sistema e di integrazione durante lo sviluppo per la prima piattaforma. Questa è una buona pratica anche per progetti una tantum, ma i vantaggi si moltiplicano quando si implementano più volte la stessa funzionalità. Non sono sicuro di come siano gli strumenti per lo sviluppo iOS, ma so che ci sono strumenti che puoi utilizzare per guidare i test dell'interfaccia utente in Android, ad esempio.

Se i test sono scritti in anticipo (meglio) o aggiunti come vai (meglio di niente), quando hai finito la prima versione, hai anche una specifica completa, dettagliata e eseguibile . Inoltre, è garantito che sia accurato - qualcosa che raramente è vero per le specifiche della carta. Usa gli stessi test per guidare il tuo sviluppo per le altre piattaforme (possibilmente con qualche tweeking) e sarai sicuro di avere uniformità di comportamento anche se non puoi condividere una base di codice.

Esegui una proposta di design all'inizio della fase 2

Una volta che lo sviluppatore ha capito come lo faranno, fanno una rapida proposta di stand-up al resto della squadra. Questo dovrebbe essere breve, scattante e al punto, ma fondamentalmente attraversare i punti chiave di

1. Che cosa intendi fare
2. Cosa hai deciso di non fare e perché

Alcuni diagrammi di supporto sono davvero utili per la proposta e possono essere memorizzati nella tua wiki. Ma non senti il bisogno di farli sempre in uno strumento di diagrammi, uno scarabocchio di lavagna che viene poi fotografato va bene.

Durante lo stand-up gli altri sviluppatori possono capire rapidamente che cosa si sta facendo, vedere il pensiero dietro di esso e sfidarlo, se del caso, prima che si compiano troppi sforzi.

Come risultato, ora hai passato anche loro le informazioni - quindi ciò che viene archiviato nel wiki deve essere solo un promemoria piuttosto che un record completo definitivo. Quindi archivia semplicemente i diagrammi con alcune note per coprire le domande chiave e i punti sollevati durante lo stand-up della proposta.

Se sei davvero appassionato (o se lo sviluppatore pensa di scrivere le poche note richieste è troppo oneroso) potresti semplicemente video la proposta e archiviarla.

Vale la pena ricordare che il punto chiave n. 2 sopra è tanto importante da registrare quanto il primo - riduce la possibilità che le persone spendano gli sforzi in futuro andando "bene chiaramente avrebbe dovuto essere fatto in questo modo ... oh aspetta ora capisco perché non l'hanno fatto ".

Perché stai documentando? Non è perché i tuoi clienti chiedono che tu sia conforme ISOxxxx, non è quello di metterlo in un elenco di funzionalità, è perché pensi che ti farà risparmiare tempo a lungo termine. Così dicendo che non hai tempo per fare qualcosa che il tempo salva ha senso solo in un paio di situazioni:

1. Facendolo più tardi ti consentirai di fare cose che ti fanno crescere abbastanza da renderlo un problema più piccolo in seguito, in relazione alla tua dimensione.

2. Stai perdendo tempo di proposito.

Se stai crescendo così velocemente che si applica # 1, smetti di leggerlo e torna al lavoro.

In caso contrario, la prima volta che la documentazione produce valore si verifica quando si effettua il porting su altre piattaforme. Piuttosto che comunicare ciò che attualmente comunichi in modo informale, scriverlo. Farlo più tardi fa perdere parte del valore che avrebbe prodotto.