Software Architecture Deliverables - Provide The Story

It is time to end another season.  At this point, we need to revisit the idea of software architecture deliverables.  In particular, we should spend some time thinking about how we communicate our architecture.

Multiple Audiences for Software Architecture Deliverables

First and foremost, there are a couple of levels of audiences that your deliverables will need to address.  This situation is always one of the most challenging to handle correctly.  Fortunately, we have other types of documents to learn from.  We can look to similar deliverables like an RFP (or response to an RFP) for a structure and approach that makes sense.

A Tiered Response

Our prior discussions have covered this sort of "tiered response" or communication.  We can craft a series of sections to communicate a growing level of detail.  Therefore, we start with a summary, then move into core details, and finally supporting documentation.  In this case, those sections cover executives, then implementors, and then architects or assessors of our work.

The sections of the software architecture deliverables should flow nicely into the areas we want to address.  The summary addresses significant decisions and the overall environment.  We then move into the actual architecture.  This section is often the most substantial part of our deliverables and critical for proper implementation.  We can provide an addendum or an appendix to address the "backstory" of our architecture and details about our thought processes behind the design.

Focus on The Varied Questions

The critical facet of each section we have mentioned is how we address questions for the target audience.  These issues should be treated as part of creating our deliverables.  For example, managers and executives are going to need some points they can share with others about the general structure and platform.  The implementation team is going to need detailed descriptions of how the provided architecture should be implemented.  They will want to see how all the pieces go together and how to build each piece.  Those that come after you will want to know what options were considered, why you chose what you chose, and paths that were willfully ignored.