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.

Rob Broadhead

Rob is a founder of, and frequent contributor to, Develpreneur. This includes the Building Better Developers podcast. He is also a longtime student of technology as a developer, designer, and manager of software solutions. Rob is a founder and principle of RB Consulting and has managed to author a book about his family experiences. In his free time, he stays busy raising five children (although a few have grown into adults). When he has a chance to breathe, he is on the ice playing hockey to relax.

Leave a Reply