Un documento di progettazione dovrebbe contenere una discussione dei pro / contro su un dato progetto o dovrebbe concentrarsi su fatti e logica?

Se i pro e i contro possono essere riassunti in una o due frasi, allora è OK metterli in un documento di progettazione. Qualche cosa di più dovrebbe essere separato.

Dove lavoro attualmente, di solito c'è un documento separato "Design decori" per tenere traccia di tutte le decisioni Grandi 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 ")," pros "(come" Facile per gli utenti da gestire ")," contro "(come" non abbastanza sicuro per la conformità ABC-XYZ ") e una conclusione che spiega perché è stata scelta una decisione particolare (ad esempio "FTP non verrà utilizzato perché non sarà in grado di soddisfare determinati requisiti di conformità"). Solitamente il documento di progettazione fa riferimento solo alla decisione scelta e può consigliare ai lettori di leggere il documento di decrizione per una descrizione completa delle altre opzioni.

Should a design document stick to raw facts ("this is the design") and rationale ("here is why this is the design") or should it also be used to point out non-defective issues with the design that could be problematic for future developers?

Non è "né-né".

Nessuno legge la documentazione in primo luogo. Sfiorano al meglio. Pertanto, scrivi il minor numero possibile di documenti. Un documento per cui tutti hanno 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. Per lo più non è aggiornato.

Vantaggi di più documenti? Nessuno.

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

Evita di stringere le mani.

Un documento pro-e-contro può trascinarsi in profondità indefinite di discorsi what-if e attraente fastidiosi.

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

Concentrati su ciò che è.

Mantieni ciò che non è giù per le ossa nude.

Se hai fatto benchmark, studi o alternative effettivamente esplorate, documentalo. Ma se stai considerando solo le alternative, riduci a icona.

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

• Hai avuto un problema? Aggiustato? Ci sono volute settimane? Davvero faticato? A malapena un aneddoto interessante. È stato risolto nel codice. Le versioni precedenti, versioni errate, versioni buggy e versioni a basse prestazioni non contano. Sono il foraggio dei blog al meglio.

• Hai ancora un problema? Non riparato? Ciò significa che ci sono alternative. Documenta questo.

Ci sono 3 fatti importanti nel processo decisionale:

• Che cosa è stato provato e non ha funzionato (e perché non ha funzionato, perché stai mirando a un target in movimento)
• Che cos'è
• Cosa potrebbe essere (aspettando solo che X sia implementato ...)

Tuttavia, a parte "Cosa c'è", tutti gli altri confonderanno il lettore e impediranno che lei perda il sistema.

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

Pertanto, vorrei sviluppare l'idea esposta @FrustratedWithFormsDesigner, con una svolta. Invece di creare un altro documento, con un ciclo di vita a sé stante, vorrei aggiungere una sezione di allegato. Quindi, per ciascuna decisione meritevole di discussione, indicherei la voce pertinente in allegato.

Sì. Un documento di progettazione dovrebbe spiegare i vantaggi, i rischi e le ipotesi associati al progetto descritto. Un documento di design ha diversi scopi:

1. 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.

2. Comunicare il design a persone non tecniche che lavorano al progetto.

3. Assistenza nella pianificazione, allocazione delle risorse, stima dei costi e altri tipi di pianificazione.

4. Diventa una parte importante della documentazione generale del progetto. Quando ti iscrivi a un progetto in corso o devi mantenerne uno completato, la vita è molto più semplice se c'è un documento di design ben scritto.

5. Spesso è uno dei risultati richiesti per contratto.

(Ci sono probabilmente 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:

1. È essenziale che tutti i membri del team sappiano quali sono i rischi ei benefici in modo che possano lavorare insieme per evitare tali rischi e sfruttare al meglio i vantaggi del design.

2. Per i membri del team non tecnici, la comprensione dei rischi e dei benefici è spesso più importante dei dettagli del design stesso.

3. La gestione del rischio è 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. Dovrebbe spettare a un manager decidere come affrontare i rischi, ma è responsabilità del progettista segnalare i rischi noti del progetto.

4. Anche quando un rischio non è più un problema, è spesso utile documentarlo perché può aiutare a spiegare la situazione al momento della creazione del disegno. Ciò può consentire a un manutentore di decidere qualcosa del tipo: "Okay, l'hanno fatto in questo modo perché ... ma non è più un problema, quindi posso sostituire quel codice con un'implementazione più semplice e veloce." Lo stesso vale per i vantaggi, naturalmente.

5. Se stai lavorando a un progetto per un cliente, è particolarmente importante documentare rischi e benefici. Ciò avverte il cliente che alcune cose potrebbero andare storte in determinate circostanze, o che richiedere modifiche al design potrebbe compromettere alcuni dei benefici promessi.

Traggo 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 cercare di documentarli dopo il fatto. Tuttavia, ora hai il vantaggio del senno di poi come puoi vedere le parti del design originale che non hanno funzionato così bene. Penso che dovresti o: aggiungere una sezione separata che identifica le attuali aree problematiche e propone soluzioni (compresi i rischi associati!); o creare un documento separato che faccia la stessa cosa. Questa nuova sezione / documento potrebbe evolvere nel documento di progettazione per la prossima versione del software.

Ecco un post sul blog per scrivere i documenti di progettazione che potresti trovare utile.

Se ci sono validi motivi per evitare soluzioni più ovvie o standard, è necessario tenerne conto. Risparmierai un sacco di guai. Tuttavia, una particolare tecnologia potrebbe migliorare nel tempo, quindi le tue ragioni potrebbero non essere applicabili. Un futuro sviluppatore può quindi utilizzare il proprio giudizio.

Non so se ci sono molti vantaggi nell'indicare tutti i cortocircuiti. Potrebbe non essere pratico apportare modifiche o altre priorità. Potresti correggerne alcuni nel prossimo futuro e questa sarà solo un'altra cosa da aggiornare.

Personalmente non lo inserisco nel documento di progettazione. Un documento di progettazione dovrebbe delineare come è, non perché è così.

Se ritieni che vi sia una buona necessità di una storia retrospettiva sul motivo per cui il design è così com'è, forse dovresti metterlo in un articolo wiki (o qualsiasi altra base di conoscenza utilizzata dalla tua azienda) in modo che possa esserci un storia dell'evoluzione del design. Le persone possono andare a leggerlo, modificarlo e aggiungere suggerimenti. In questo modo si tratta più di una discussione aperta anziché di un battito di fronte in un documento.

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

In ogni caso,

nel processo di aggiornamento di un documento di design scritto da qualcun altro, rimarrei umile e non tentare di indovinare perché tale decisione è stata presa.

Inserirò le motivazioni solo sulle modifiche apportate alla progettazione durante la manutenzione.