Documenting Design Decisions

December 16, 2013 | , ,

We previously discussed Options Analysis – our method for evaluating multiple viable technical solutions.  We also facilitate numerous smaller design choices at all levels of the architecture.  We often need to document these as “design decisions,” and use a common approach and format to document at all levels of design (conceptual, logical, physical, component, etc.).

 

Now, before we get too deep into this whole design decision thing, let’s clarify the Systems Flow perspective.  We have previously presented our stance on prose as the lowest form of design content and, although we structure decisions nicely in a table, they are not diagrams.  They are prose, and as such, we avoid them whenever possible.
In our Investigative Architecture™ approach we define 3 – and only 3! – conditions for scribing a design decision:
  1. Analysis or debate went into an architecture choice and should be documented for posterity.  Only bother documenting these if you want to avoid rehashing the topic in about a year or so.
  2. A tactical choice was made over a strategic preference and is known not to be the architecture end-state.  Ideally these would also be tracked as exceptions via some architecture governance process.  Decisions of this type will always be linked to the risks associated with the choice.
  3. Something is otherwise not clear (“the 5%”).  An architecture choice was made and the ramifications are not at all obvious from the rest of the formal design- i.e. there is no better “home” for the information.

For category 1 or 2, an options analysis of some sort will occur, either a formal solution options analysis or a smaller options discussion or review, resulting in a final decision that needs to be documented with the design.  If a formal analysis is conducted, be sure to reference the formal analysis artifact when summarizing the final decision using a design decision.

Anatomy of a Design Decision

We structure our decisions as table formatted blocks within the design artifact.  Often times we will put the decision blocks in an appendix, then render the decision statements in a table in the main body of the document.

Notes

  • Id: Every decision is assigned a unique number (scope of uniqueness is the document)
  • Decision Statement:  Structure as a statement of fact.  “Data will not be encrypted at rest.” Ensure it covers the entire scope of decision and no details are hidden in the Analysis section.  Assume your audience will ignore any details provided in the remainder of the block.
  • Analysis: Be comprehensive!  Although we avoid unnecessary verbiage at all costs, when you’ve facilitated an important decision, don’t leave any important background point out or gloss over it.  If a very detail-oriented stakeholder who is antagonistic to the decision being made were to read your rationale and analysis, would they have legitimate grounds to challenge your analysis and the method used to reach the decision? If so, your analysis probably needs to be more complete.
So, in summary: don’t document design decisions.  Unless you absolutely must!  And when you absolutely must, have some organizational standard for doing so, like the one above.  If you want to learn more read some of our other articles on design or feel free to contact us.
The following two tabs change content below.

Dan Hughes

Was a principal consultant at Systems Flow, Inc.

Latest posts by Dan Hughes (see all)



Comments

Comments are closed.