Un documento di design dovrebbe contenere una discussione dei pro / contro di un determinato design o dovrebbe concentrarsi su fatti e motivazioni?

13

Attualmente sto aggiornando un documento di progettazione in modo che sia corretto e aggiornato per i futuri sviluppatori.

Attualmente, il documento si concentra solo sui fatti, presentando come è il design. Non vi è alcuna motivazione per le decisioni presentate. Credo che sia importante catturare la logica in modo che gli sviluppatori sappiano perché qualcosa è così com'è, poiché ciò influenzerà probabilmente le decisioni future. Non è possibile per me aggiungere una logica per tutte le decisioni di progettazione, in particolare quelle prese prima di iniziare a lavorare al progetto, ma sto facendo quello che posso in questo dipartimento.

Tuttavia, alcune delle decisioni di progettazione sono, rispettosamente, decisioni molto povere dati i requisiti del progetto. Ce ne sono anche alcuni buoni.

Il mio pensiero iniziale era che avrei dovuto includere una discussione sui problemi di progettazione e potenziali soluzioni o soluzioni alternative a questi problemi per focalizzare l'attenzione dei futuri manutentori, ma non sono sicuro che il documento di progettazione sia un posto per questo tipo di discussione e informazione. Non voglio che una "critica" di design si trasformi in "lanciando questo design nuovo" mentre altre persone lavorano su questo sistema e aggiornano il documento, dato che è chiaramente inappropriato.

Il mio manager sosterrebbe entrambe le decisioni, quindi dipende da me. Indipendentemente dall'approccio che seguo, il documento prodotto verrebbe ufficialmente aggiornato e fornito agli sviluppatori che lavorano sul sistema, in genere prima che vengano incaricati del lavoro di sviluppo. Si prevede che un nuovo sviluppatore familiarizzi con i documenti associati a un determinato sistema software prima di iniziare il lavoro di sviluppo.

Domande:

Se un documento di design dovesse attenersi a fatti grezzi ("questo è il design") e alla logica ("ecco perché questo è il design") o dovrebbe essere usato anche per evidenziare problemi non difettosi con il design che potrebbero essere problematici per futuri sviluppatori?
Se il documento di progettazione non deve essere utilizzato per acquisire queste informazioni, quale tipo di documento dovrebbe acquisirle e cos'altro deve essere acquisito con una discussione su motivi di progettazione, compromessi e problemi noti (che non sono difetti, poiché i difetti vengono tracciati usando altri strumenti)?

design documentation

— Thomas Owens
fonte

1

I documenti di progettazione non sono il luogo adatto per tali critiche, ma è importante che tali preoccupazioni siano trasmesse con mezzi adeguati.

— Robert Harvey,

1

@Robert Mi sembra proprio una risposta, anche se forse espandere su ciò che considereresti appropriato significa.

— Thomas Owens

Errata, forse, o Richieste di commento. I documenti di progettazione dovrebbero passare attraverso un processo di revisione formale (più o meno). Consentire alle persone di contrassegnare un documento di questo tipo con critiche sembra contrario a tale processo, a meno che non si utilizzi qualcosa come "commenti a margine" in un documento di Word (possono essere disattivati, mostrando il documento "ufficiale").

— Robert Harvey,

7

Se i pro e i contro possono essere riassunti in una frase o due, allora va bene inserirli in un documento di progettazione. Qualcosa di più dovrebbe essere separato.

Dove attualmente lavoro, di solito esiste un documento separato "Decisioni di design" per tenere traccia di tutte le decisioni importanti e importanti. Spesso formattato con un paragrafo che descrive il problema (come "Alcuni file devono essere spostati da un server a determinati utenti alla fine di ogni ciclo di elaborazione, ci sono molti modi per farlo ..."), una tabella con colonne " descrizione della soluzione "(come" sposta file via FTP ")," pro "(come" Facile da gestire per gli utenti ")," contro "(come" non abbastanza sicuro per la conformità ABC-XYZ ") e una conclusione che spiega perché è stata scelta una determinata decisione (ad esempio "FTP non verrà utilizzato perché non sarà in grado di soddisfare determinati requisiti di conformità"). Il documento di progettazione di solito fa riferimento solo alla decisione scelta,

— FrustratedWithFormsDesigner
fonte

Mi piace abbastanza quel formato. Potrei doverlo prendere in prestito / rubarlo per provarlo, se non ti dispiace. Forse lo farò anche da modello aziendale e lo passerò in giro per il mio team, se funziona bene per me e non ci sono obiezioni da parte tua.

— Thomas Owens

2

@Thomas Owens: provaci! Funziona bene qui, e mi piace anche. :) Non credo che tu possa "rubarlo" dato che so che le persone in altre società fanno cose simili, non è quasi "nuovo";)

— FrustratedWithFormsDesigner

5

Se un documento di design dovesse attenersi a fatti grezzi ("questo è il design") e alla logica ("ecco perché questo è il design") o dovrebbe essere usato anche per evidenziare problemi non difettosi con il design che potrebbero essere problematici per futuri sviluppatori?

Non è "né-né".

Nessuno legge la documentazione in primo luogo. Scremano - nella migliore delle ipotesi. Pertanto, scrivi il minor numero di documenti possibile. Un documento è tutto ciò per cui chiunque ha pazienza. È improbabile che un secondo documento "non desgin" con "altri problemi" venga letto.

Vantaggi di un documento? Le persone potrebbero leggerlo.

Svantaggi di un documento? Pochi. Principalmente diventa obsoleto.

Vantaggi di più documenti? Nessuna.

Svantaggi di più documenti? Si prega di leggere il principio DRY e la programmazione alfabetica. Più documenti significa più fonti di errori. Ogni documento non è d'accordo con l'altro e non è d'accordo con il codice. Questo è abbastanza ovvio. Questo è il percorso della follia.

Evitare di strizzare le mani.

Un documento pro-e-contro può trascinarsi in profondità indefinite di what-if e interessanti discussioni fastidiose.

Se ritieni che sia necessario presentare pro e contro, tienilo breve e al punto.

Concentrati su ciò che è.

Mantieni ciò che non dipende dalle ossa nude.

Se hai fatto benchmark, studi o effettivamente esplorato alternative, documentalo. Ma se stai solo considerando delle alternative, minimizzale.

Questa non dovrebbe essere la tua storia personale di prove e tribolazioni.

Hai avuto un problema? Aggiustato? Ci sono volute settimane? Davvero lottato? A malapena un aneddoto interessante. È stato corretto nel codice. Le versioni precedenti, le versioni errate, le versioni con errori e le versioni a basse prestazioni non contano. Nel migliore dei casi sono blog-foraggio.
Hai ancora problemi? Non riparato? Ciò significa che ci sono alternative. Documentalo.

— S. Lott
fonte

Le tue ultime due frasi sono particolarmente vere. Tutto ciò che avevo intenzione di discutere era o problemi che ho dovuto affrontare nell'implementazione di una funzione / correzione di un difetto, nella scrittura di test o scoperti durante la profilazione e non solo una critica complessiva del progetto nel suo insieme. Mi consiglia di documentarlo nel documento di progettazione o in un documento separato?

— Thomas Owens

"problemi che ho affrontato"? Essenzialmente irrilevante. Il codice è la soluzione, il problema è di solito solo un commento. "scoperto durante la profilazione" significa che è stato risolto, quindi è nel passato e non ha alcuna rilevanza. Non utilizzarlo come esercizio di "journaling".

— S.Lott

Alcuni problemi che ho riscontrato avrebbero un impatto su futuri miglioramenti / difetti nello stesso modulo, come una dipendenza precedentemente non documentata che, di per sé non è un difetto (quindi non può essere archiviato come uno), ma cambia il modo in cui necessità di affrontare i problemi in determinati moduli. Questo è così strettamente associato al sistema che non può essere modificato a questo punto con un ragionevole sforzo. Questo deve essere catturato da qualche parte per riferimento. Inoltre, la profilazione è stata uno sforzo di accertamento dei fatti, nulla è stato risolto: esistono ancora e soddisfano ancora i requisiti attuali, ma sono potenzialmente problemi futuri.

— Thomas Owens

Giusto per chiarire di più. Un esempio è che avevo un difetto A che ho risolto. Tuttavia, durante la correzione di A, ho riscontrato diversi problemi non documentati. Questo è ora documentato nel codice, ma deve essere catturato anche altrove. In genere è al di sotto del livello di classe e all'interno dei metodi, quindi queste relazioni e potenziali problemi non verrebbero catturati in un diagramma di classe o diagramma di sequenza. Non possono essere riparati o risolti con un ragionevole sforzo e non causano problemi funzionali o di prestazione. Come devo catturare al meglio queste informazioni al di fuori del codice?

— Thomas Owens

1

@Thomas Owens: considera di essere unico e tutti gli altri sono pigri. "Non riesco a immaginare nessuno che non lo faccia". Devi incontrare più persone e vedere quanto poco materiale viene messo nella documentazione. Per esempio. Centinaia di domande StackOverflow - ogni giorno - ottengono una risposta banale da tutorial. Ancora. La gente non legge e fa domande perfettamente stupide. Posso solo ripetere ciò che ho osservato negli ultimi 3 decenni. La gente non legge. La tua esperienza potrebbe essere diversa. Hai chiesto consiglio. L'ho dato a te.

— S.Lott

2

Ci sono 3 fatti importanti nel processo decisionale:

Cosa è stato provato e non ha funzionato (e perché non ha funzionato, perché stai prendendo di mira un bersaglio mobile)
Cosa è
Cosa potrebbe essere (sto solo aspettando l'implementazione di X ...)

Tuttavia, a parte "Ciò che è", tutti gli altri confonderanno il lettore e le impediranno di far breccia nel sistema.

Mi piace l'idea di catturare gli altri 2, anche se sono meno interessanti per l'apprendimento del sistema, possono essere un risparmio di tempo quando lo si cambia.

Pertanto, vorrei basarmi sull'idea esposta @FrustratedWithFormsDesigner, con una svolta. Invece di creare ancora un altro documento, con un suo ciclo di vita, affronterei una sezione dell'allegato. Quindi, per ogni decisione degna di discussione, vorrei indicare la voce pertinente in allegato.

— Matthieu M.
fonte

1

Sì. Un documento di progettazione dovrebbe spiegare i vantaggi, i rischi e i presupposti associati alla progettazione descritta. Un documento di progettazione ha diversi scopi:

Prendi il disegno scritto in modo che tutti lo capiscano e in modo che la comprensione di ogni persona non vada alla deriva nel tempo.
Comunicare il progetto a persone non tecniche che lavorano al progetto.
Assistenza nella pianificazione, allocazione delle risorse, stima dei costi e altri tipi di pianificazione.
Diventa una parte importante della documentazione generale del progetto. Quando ti unisci a un progetto in corso o devi mantenerne uno completato, la vita è molto più semplice se c'è un documento di design ben scritto.
È spesso uno dei risultati richiesti dal contratto.

(Probabilmente ce ne sono altri, ma questi sono un buon inizio.)

Ognuno di questi scopi è ben servito da un documento di progettazione che spiega chiaramente perché questo progetto è stato scelto e quali sono i rischi associati:

È essenziale che tutti i membri del team sappiano quali sono i rischi e i benefici in modo che possano lavorare insieme per evitare tali rischi e sfruttare al meglio i vantaggi del design.
Per i membri del team non tecnici, la comprensione dei rischi e dei benefici è spesso più importante dei dettagli del progetto stesso.
La gestione dei rischi è una delle cose più importanti che un project manager può fare per garantire il successo e il primo passo è identificare i rischi che devono essere gestiti. Spetta a un manager decidere come gestire i rischi, ma è responsabilità del progettista indicare i rischi noti della progettazione.
Anche quando un rischio non è più un problema, è spesso utile documentarlo perché può aiutare a spiegare la situazione al momento della creazione del progetto. Ciò può consentire a un manutentore di decidere qualcosa del tipo: "Okay, lo hanno fatto in quel momento perché ... ma non è più un problema, quindi posso sostituire quel codice con un'implementazione più semplice e veloce." Lo stesso vale per i benefici, ovviamente.
Se stai lavorando a un progetto per un cliente, è particolarmente importante documentare rischi e benefici. Ciò mette in guardia il cliente che le cose potrebbero andare storte in determinate circostanze o che richiedere modifiche al design potrebbe compromettere alcuni dei vantaggi promessi.

Raccolgo dalla domanda che stai lavorando con un documento di progettazione esistente per un sistema che è già stato implementato. In tal caso, molti dei possibili rischi non sono più rischi, quindi non ha molto senso provare a documentarli dopo il fatto. Tuttavia, ora hai il vantaggio del senno di poi in quanto puoi vedere le parti del design originale che non hanno funzionato così bene. Penso che dovresti: aggiungere una sezione separata che identifichi le attuali aree problematiche e proponga soluzioni (compresi i rischi associati!); o creare un documento separato che faccia la stessa cosa. Questa nuova sezione / documento potrebbe evolversi nel documento di progettazione per la prossima versione del software.

Ecco un post sul blog su come scrivere documenti di design che potresti trovare utile.

— Caleb
fonte

0

Se esistessero validi motivi per evitare soluzioni più ovvie o standard, è opportuno prenderne atto. Salverai molti problemi a qualcuno. Tuttavia, una particolare tecnologia potrebbe migliorare nel tempo, pertanto i motivi potrebbero non essere applicabili. Un futuro sviluppatore può quindi usare il proprio giudizio.

Non so se ci siano molti vantaggi nel sottolineare tutte le carenze. Potrebbe non essere pratico apportare le modifiche o avranno luogo altre priorità. Potresti risolverne alcuni nel prossimo futuro e questa sarà solo un'altra cosa da aggiornare.

— Jeffo
fonte

Non sono necessariamente cose che possono essere riparate, ma la maggior parte sono "gotchas" che molte persone potrebbero trascurare o aree che non sono del tutto ovvie in che modo sono correlate. Un approccio sensibile al tempo è comunque una buona idea. Questa applicazione ha circa 5 anni e all'epoca avevano semplicemente accesso a diversi strumenti e tecnologie, e questo deve essere tenuto presente, indipendentemente dall'approccio che seguo,

— Thomas Owens

0

Personalmente non l'avrei inserito nel documento di progettazione. Un documento di progettazione dovrebbe delineare com'è, non perché lo sia.

Se ritieni che vi sia un buon bisogno di una storia retrospettiva sul perché il design è così com'è, forse dovresti metterlo in un articolo wiki (o qualunque base di conoscenza utilizzata dalla tua azienda) in modo che possa esserci una storia del evoluzione del design. Le persone possono andare a leggerlo, modificarlo e aggiungere suggerimenti. In questo modo è più una discussione aperta invece che un sopracciglio che batte in un documento.

— Tyanna
fonte

Tutta la documentazione e le conoscenze sono conservate in documenti Word, fogli di calcolo Excel, diagrammi di Visio o Rational e presentazioni PowerPoint con versione. O avrei bisogno di aggiungere al documento di progettazione o creare un nuovo documento con uno strumento e una versione che nel repository di documenti per il progetto.

— Thomas Owens

@Thomas Owens - Vedo la tua situazione quindi. Non lo metterei ancora nel documento principale, ma quel tipo di discussione è buona e non dovrebbe limitarsi a vivere nei ricordi degli sviluppatori originali. Forse aggiungerlo come commenti sul documento principale stesso? In questo modo puoi dare un'idea senza che sia parte del testo principale.

— Tyanna,

0

Sono d'accordo con te sul mettere la logica nel documento di progettazione.

Comunque,

nel processo di aggiornamento di un documento di progettazione scritto da qualcun altro, rimarrei umile e non proverei a indovinare perché tale decisione sia stata presa.

Così,

Vorrei inserire la logica solo sulle modifiche apportate al progetto durante la manutenzione.

— mouviciel
fonte

Sicuramente l'ultima frase. Non so perché Jim, Bob e Steve abbiano deciso di progettare la loro app in questo modo, quindi non proverò nemmeno a razionalizzarla. Posso, tuttavia, assicurarmi che un determinato modulo o componente sia associato ai requisiti e anche razionalizzare le decisioni che ho preso.

— Thomas Owens