Qual è un modo efficace per registrare le motivazioni alla base delle decisioni di progettazione del prodotto?


30

Nella nostra azienda non utilizziamo alcun documento di progettazione del prodotto. Abbiamo un totale di tre dipendenti, quindi tutte le discussioni sulla progettazione del prodotto si svolgono di persona o su Slack. (Siamo anche sul pacchetto Slack di base che consente solo la visualizzazione dei messaggi più recenti.)

Il nostro prodotto è ancora in fase iniziale e spesso rivisitiamo elementi di design decisi mesi fa.

Un problema che affrontiamo su una base dolorosamente frequente è dimenticare perché è stata presa una decisione di progettazione del prodotto. Ciò si traduce in ore sprecate a ricostruire lo stesso terreno.

Come possiamo registrare efficacemente le motivazioni alla base delle decisioni di progettazione?

Il nostro flusso di lavoro si basa su Pivotal Tracker. Una soluzione che mi viene in mente è quella di registrare le motivazioni di tutte le decisioni di progettazione rilevanti come commenti sulla storia dell'utente stesso, ma questo sembra inaffidabile.

Per essere chiari al 100%: non sto parlando della progettazione del codice. Sto parlando del design del prodotto realizzato dal codice. In altre parole, non sto parlando di decisioni come "dovremmo strutturare questa classe usando la composizione piuttosto che l'eredità multipla?"; Sto parlando di decisioni come "dovremmo richiedere a un utente di confermare il proprio indirizzo e-mail prima di poter accedere?".

Lo scopo della documentazione è quello di consentire all'azienda di visualizzare una registrazione del perché sono state prese le decisioni, di aiutare a prendere ulteriori decisioni sugli stessi argomenti.


13
Se ritieni di aver bisogno di una forma di documento di progettazione, perché non creare un documento di progettazione?
MetaFight,

Suppongo che i razionali saranno registrati come prosa, prosa scritta a prima ipotesi. Chi è il lettore previsto per quelli?
Laurent LA RIZZA,

Perché dici che la registrazione delle storie degli utenti su Pivotal sembra inaffidabile? Non ho mai usato quel software, ma di solito un biglietto è un buon posto per registrare la motivazione per alzare il biglietto. Non inserire semplicemente "Richiedi all'utente di confermare l'indirizzo email", inserisci "Richiedi all'utente di confermare l'indirizzo email. Questo aiuta perché ..." Stai dicendo che è inaffidabile perché potresti non preoccuparti di farlo (cioè vuoi un processo che imponga di fare la cosa giusta), o inaffidabile perché le vecchie storie Pivotal scompaiono in un buco nero e non le troverai, o c'è qualche altro problema?
Steve Jessop,

Chi sono gli autori e chi sono i consumatori di questa documentazione? Mi sembra che "l'azienda" sia l'autore e tutti ne sono lettori? Sarebbe corretto? (Capisco che sei piccolo in questo momento, ma se dovessi crescere quali sarebbero le risposte?)
mlk,

Suggerirei "dovremmo richiedere a un utente di confermare il proprio indirizzo e-mail prima di poter accedere?" il tipo di decisioni dovrebbe rientrare nei criteri di accettazione.
Kumards,

Risposte:


26

Registri le motivazioni alla base delle decisioni di progettazione scrivendole. Idealmente vicino all'oggetto che è soggetto alla decisione (che non è una "storia utente" - le storie utente sono descrizioni di ciò che deve essere implementato, non come).

Questo è in particolare il motivo per cui vengono fatti i commenti : per registrare il motivo per cui uno specifico pezzo di codice o struttura sembra (e non sto parlando esclusivamente di commenti di codice). Se l'oggetto del tuo disegno è una funzione, fai un commento introduttivo alla funzione. Se è una classe, fai un commento all'inizio di una lezione sulla logica. Se hai un gruppo di classi che dovrebbero seguire tutte la stessa struttura, aggiungi un documento di progettazione separato (come un file "readme") al pacchetto contenente quelle classi. Se l'oggetto del tuo disegno è un diagramma UML, aggiungi commenti alla sezione descrizione del diagramma.

I documenti di progettazione IMHO possono avere il loro valore, ma se descrivono cose troppo "lontane" dall'oggetto che descrivono, tendono a diventare incoerenti molto rapidamente. Quindi la mia raccomandazione è di mettere tutta la documentazione di progettazione il più vicino possibile all'oggetto progettato.

Utilizzare documenti separati solo quando si desidera documentare decisioni di progettazione che incidono su molti punti diversi del codice in modo trasversale. Quando li usi, prova a renderli parte della tua base di codice e posizionali al livello gerarchico corrispondente dell'oggetto progettato (quindi, se prendi una decisione di progettazione per un modulo che consiste in molti file di codice sorgente, inserisci la descrizione del progetto " all'interno di quel modulo, ma non in un file di classe, non in una "descrizione di livello superiore" che è valida per altri moduli, e sicuramente non in un Wiki separato al di fuori del tuo SCCS. Se vuoi registrare un "livello elevato", prodotto ampie decisioni di progettazione, quindi un documento di livello superiore potrebbe essere il posto migliore, ma assicurati che questo documento rimanga su quel livello di astrazione.


Riguardo ai commenti: non diresti che lo scopo dei commenti è descrivere il codice? Perché il tipo di problema di cui sto parlando sono problemi di progettazione, come: l'utente deve disporre delle autorizzazioni X assegnate alle impostazioni dell'account Y? Lo scopo del codice è di abilitare il design, quindi non credo che il posto appropriato per discutere del design sia nel codice.
henrebotha,

5
@henrebotha: Sembri avere un'idea diversa da me su ciò che il design è, può essere o dovrebbe essere. Il codice è design. La struttura del codice è design. La struttura delle interfacce utente è design. La meta struttura del codice o delle classi è design. Una domanda del tipo "se l'utente ha i permessi X in base alle impostazioni dell'account Y" mi suona come qualcosa che non vuoi collegare in nessun punto del tuo software - sembra più un requisito configurabile. Il modo in cui implementi tale requisito nel codice può essere una decisione di progettazione, così puoi commentarlo da qualche parte nel tuo codice.
Doc Brown,

2
@henrebotha: se si autorizzano le autorizzazioni X per le impostazioni dell'account Y, il codice verrà influenzato da tale decisione. Un codice che controlla le autorizzazioni, un codice che gestisce le impostazioni dell'account, un codice UI, un codice controller. Quindi dovrebbe esserci un commento nel codice in tutti quei posti. Ovviamente, per evitare ripetizioni, tutti i commenti possono riferirsi a un documento di progettazione separato, se c'è una logica dietro di esso che colpisce molti luoghi diversi (come ho detto nella mia risposta) ..
Doc Brown,

1
Non sto contestando che le decisioni di progettazione influiscono sul codice. Naturalmente le decisioni di progettazione influiscono sul codice. Ciò non significa ancora che i commenti siano il posto giusto in cui registrare le decisioni di progettazione del prodotto.
henrebotha,

1
@henrebotha: dipende da cosa intendi per "Decisioni di progettazione del prodotto". Le decisioni di progettazione "a livello di prodotto" possono appartenere a un documento al "livello superiore" della documentazione del prodotto. Se intendi qualsiasi tipo di "decisione di progettazione all'interno del tuo prodotto", alcuni di essi appartengono a commenti in codice, altri no. Ma non sto solo parlando di commenti in codice, vedi la mia modifica. Sto parlando di qualsiasi forma di commento (all'interno del codice o in documenti separati) che fai parte del tuo codice.
Doc Brown,

8

Prendi in considerazione un approccio agile. Voglio dire, se hai le risorse di tempo e le eccellenti capacità di scrittura per annotare ogni decisione di progettazione che prendi insieme alle loro motivazioni, documenta tutto. Realisticamente parlando, presumo che tu non sia in una tale posizione. Un approccio agile può aiutare con una sfida chiave per la documentazione dei razionali: spesso non si sa quali razionali erano quelli importanti fino a dopo.

Affrontiamo il problema da un punto di vista olistico. Ragazzi avete delle motivazioni per la vostra decisione. Sono intrappolati in Squishyware in questo momento, il cervello della squadra. Nonostante la quantità di documentazione relativa al credito, l'archiviazione di razionali in sqishyware non è poi così male. Siamo davvero bravi come specie a ricordare le cose importanti. È per questo che ogni grande corporazione ha "conoscenza tribale", anche quando quelle corporazioni cercano di documentare tutta quella conoscenza tribale.

Ora hai un problema. Stai scoprendo che lo sqiushyware non tiene abbastanza bene le motivazioni. Bene per te per aver capito che c'è un problema e per identificare che deve essere risolto! Non è sempre un passo facile! Quindi siamo abbastanza sicuri che la soluzione sia scaricare parte di tale logica nella documentazione. Tuttavia, non è abbastanza. Non possiamo mai dimenticare la seconda metà del puzzle, che sta ricaricando la logica nello squishyware quando è necessario prendere una decisione. Ho visto un sacco di squadre che documentano tutto come un matto, ma il contenuto non è in realtà organizzato per aiutare a prendere buone decisioni, quindi finiscono per dimenticare le motivazioni anche se sono scritte .

Quindi hai un processo in due fasi. Devi estrarre la logica dallo squishyware e documentarlo. Quindi devi assicurarti che la documentazione sia organizzata abbastanza bene da riportare il razionale in squishyware quando ne hai bisogno! Ora penso che abbiamo abbastanza di una dichiarazione di problema per renderci conto di dove piaceranno le sfide. Quando stai documentando, in genere non sai chi lo guarderà in seguito, o cosa stanno cercando. Allo stesso modo, quando guardi indietro alla documentazione, in genere non sai cosa stai cercando (nella migliore delle ipotesi potresti sapere quando).

Quindi una grande azienda potrebbe provare a gestirla in due grandi blocchi. Per prima cosa possono andare a sviluppare requisiti basati su ciò di cui le persone hanno bisogno quando ricercano la documentazione. Quindi usano questi requisiti per costruire un processo per lo sviluppo di detta documentazione. E, se oso dirlo, allora tutti si lamentano perché quasi nessuno sa esattamente come dovrebbe essere la documentazione il primo giorno. La documentazione è sempre incompleta e gli sviluppatori lamentano sempre che il processo è troppo oneroso.

È ora di andare agili.

Il mio consiglio sarebbe di avviare uno sforzo agile per migliorare il processo di documentazione: i nove metri interi da squishyware a documentazione e ritorno a squishyware. Riconosci subito che perderai alcune informazioni perché il tuo processo non è perfetto, ma va bene perché stai ancora cercando di capire il processo! Ti mancherebbe di più se provassi a creare una soluzione adatta a tutte le dimensioni.

Qualche bocconcino in particolare guarderei: * Esplora la documentazione informale. La documentazione formale è ottima, ma richiede molto tempo. Uno degli scopi della documentazione è di rilasciare informazioni dallo sviluppatore squishyware e metterle su carta. La documentazione informale riduce al minimo i costi per farlo.

  • Accetta formati di documentazione non affidabili. Nulla andrà bene la prima volta. È meglio ottenere i dati e capire come renderli affidabili in seguito. Ad esempio, potresti documentare le tue motivazioni in un blocco <rationale> </rationale> o qualcosa di simile, il che renderebbe più semplice raccogliere quei dati in un secondo momento. Memorizzare le motivazioni in una user story, per ora, va bene!
  • Non dimenticare mai il valore dell'organizzazione. Scopri come a te, come squadra, piace cercare razionali nella documentazione e provare a documentare ciò. Ogni squadra avrà un processo diverso. In una delle mie squadre, non siamo mai riusciti a trovare subito il biglietto con la motivazione. Quello che potremmo fare è trovare una riga di codice che conta, fare un svn blameper scoprire quando è cambiato e perché, quindi andare a vedere i biglietti. Una volta che eravamo lì, in genere mettevamo tutta la logica di cui avevamo bisogno proprio sul biglietto. Ha funzionato per noi, scopri cosa funziona per te.
  • La documentazione organica può crescere nel tempo. È raro che gli sviluppatori sappiano quali razionali sono più importanti il ​​giorno in cui hanno bisogno di scriverlo. Di solito scopriamo quali erano importanti in seguito. Se si dispone di un processo di preparazione della documentazione che consente agli sviluppatori di gestire il proprio piccolo giardino di razionali, quelli importanti emergeranno in superficie. Ancora più importante, i razionali possono cambiare. Potresti capire che due diversi cambiamenti, con due razionali diversi, sono stati descritti al meglio da un'unica logica che funziona per entrambi. Ora c'è meno contenuto tra te e le decisioni!

0

Suggerirei di configurare un'istanza privata di MediaWiki o di un software wiki simile. È davvero facile organizzare e riorganizzare i contenuti lì, e puoi copiare e incollare nuove discussioni direttamente nella scheda discussioni degli articoli wiki pertinenti. Abbiamo usato MediaWiki nel mio ultimo lavoro per tutta la nostra architettura e i documenti API, ed è stato un vero toccasana.


2
Architettura e decisioni di alto livello - potrebbe essere ok. Documenti API - NO! Alcune persone nella nostra organizzazione hanno provato questo in passato ed è sempre lo stesso: i documenti di basso livello non sono sincronizzati con il codice. I wiki non interagiscono bene con il VCS, le persone dimenticano o non si prendono il tempo per aggiornarlo, ecc. I documenti API appartengono al codice , di fronte alle funzioni che descrivono. Se ritieni di averne bisogno nella tua intranet, usa un generatore HTML come doxygen per estrarli da lì. Ma fatti un favore e non gestirli separatamente, manualmente, in un Wiki.
Doc Brown,

3
Sono fermamente convinto che tutte le motivazioni del design debbano essere scritte all'interno del repository del codice sorgente. In qualsiasi altro luogo, e non solo si discostano, ma non ricorderanno nemmeno la loro storia.
cmaster

Downvoting di una soluzione che funziona ... Wow. Va bene allora.
zerobandwidth,

0

Pensaci dal punto di vista del programmatore a cui verrà chiesto di cambiarlo tra 12 mesi.

Se si aggiunge questa regola aziendale come test automatizzato, la modifica verrà apportata E POI si otterrà dal test non riuscito il requisito contraddittorio (e si spera che si acquisisca la persona associata al requisito originale e il motivo della sua specifica).

Considero il documento di progettazione (il luogo in cui inserisci i tuoi diagrammi BPMN, i diagrammi delle transazioni, persino una foto della lavagna, ecc.) Come simile al codice, solo un modulo non eseguibile ... il che significa che cosa stai cercando di record è simile a un commento di codice, ma un requisito (verificabile) specificato in anticipo nel progetto. Presumibilmente, se sei un negozio agile, continui a progettare il tuo codice, lo fai solo all'ultimo minuto prima di scriverlo. Conservare questo nella base di codice con tutti gli altri documenti di progetto.

Qualunque cosa tu faccia, assicurati che sia memorizzato in un modo che sia ricercabile (ad esempio potresti voler estrarre tutte le regole di business relative alla "autenticazione" quando specifichi nuove modifiche).


0

Come sempre quando scrivi qualcosa, devi chiederti chi sia il pubblico previsto. Sono fermamente convinto che i documenti di progettazione siano disponibili per i miei sviluppatori peer, attuali o futuri. Il documento li aiuta a capire cosa sto costruendo o cosa è stato costruito (panoramica di alto livello) e, soprattutto, perché. È un posto per documentare le alternative che hai considerato, i pro ei contro di ciascuna.

Dire che va bene che un po 'di design viva nel cervello delle persone lascia fuori che gli sviluppatori passino e trovino diversi lavori, portando con sé quelle informazioni preziose.

Avere il tuo codice come unica documentazione di progettazione è come orientarti in città usando una lente d'ingrandimento. Una mappa è molto più utile (purtroppo non esiste un equivalente GPS per il codice sorgente).

Sono d'accordo sul fatto che la documentazione di progettazione marcisce anche più velocemente del codice. E poiché non esiste alcuna convalida possibile tra i due, l'unica cosa che puoi fare è tenerli vicini. IMO, un documento di progettazione datato fornisce ancora informazioni preziose.

Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.