Architectural Documentation - Communicate Your Decisions

At some point in your project, architectural documentation becomes an essential piece of the deliverables.  This material is often a set of diagrams and bullet points.  However, there is more that we need to include.  A good set of deliverables will consist of some defense of the decisions made.  While this defense is good for CYA, it is more important when someone needs to consider whether a change is required.

Basic Architectural Documentation

The typical set of deliverables to achieve this goal covers what direction the implementation team should take.  It is roughly a laundry list of decisions made and enough explanation to act on those.  The result is a summary of the decisions made. That is in contrast to a synopsis of how the core decisions were made.  Think of it as a set of marching orders with a "need-to-know" level of detail.

There are situations where this makes sense.  Some teams will only get bogged down when you provide them with high-level arguments.  In those cases, the most direct and simplified architecture will be best for them to implement.

Defending Your Decisions

The goal of providing some history and defense of your decisions is not a means for those decisions to be second-guessed.  Instead, you will help future architects avoid re-inventing the wheel.  Think of it as similar to legal precedence in the court system.  Rather than walk back through all of the possible sources and arguments, we can lean on the expertise of others to build on their work.

A simple case is one where a vendor tool is selected.  The vendors considered during the selection process and scoring rubric will help anyone that is asked to review that selection in a potentially new light.  For example, a "new" vendor may become a hot topic in the industry. You can either score them against the criteria used or at update the scorecard for all vendors with a lot of the leg work done on those older vendors.  You might even find that the "new" vendor was already considered.

Allow For Change

The critical point in all of this is to provide content that can be used when technology or requirements change.  We know they will.  Thus, the context around your decisions is crucial.  This information will provide a quick view of your thought process.  That can shorten the work required for future decisions.