Documenting Design Decisions

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.
Dan Hughes
Dan Hughes is a principal consultant and partner at Systems Flow, Inc., where he leads the technology services practice. He has 20 years of software engineering experience spanning a broad range of technologies and techniques. Startup to enterprise, he has launched, managed, and executed all aspects of both product and enterprise life cycle, delivering complex, enterprise-scale architectures for clients in the public and private sector, in industries ranging from banking and insurance to international development. Dan holds a Bachelor of Science in Computer and Systems Engineering from Rensselaer Polytechnic Institute. For more details, please visit Dan's LinkedIn profile
Dan Hughes

Latest posts by Dan Hughes (see all)



Comments

Comments are closed.