By Dan Hughes of Wittij Consulting
In my last article, I talked about solution architecture diagramming. I am a huge fan of diagrams as a quick and effective way to document a solution architecture.
As a quick refresher, here are the diagrams I recommended in my prior article:
In this article, I will discuss what is essential to capture as part of a solution architecture design beyond the diagrams.
Before I get into that, here is my solution architecture documenting philosophy:
- Less is more. Anything you include in a solution architecture design document that does not contribute to forwarding an understanding of the solution architecture adds noise that distracts from the message.
- Prefer visuals. As discussed in the prior diagramming article, properly structured visuals effectively describe solution architecture.
- Avoid unstructured narratives. Unstructured narratives encourage “word salad” and filler text instead of crisp descriptions. Also, like when you diagram without a standard notation, you finish whenever you think you have finished, which is different than finishing when the information is complete. I prefer simple bulleted lists or tables when I must include narrative details.
Now let’s journey beyond the diagrams!
A solution architecture design’s most important, non-diagram element is a register of the solution architecture risks. There are usually plenty of people paying attention to the project risks, which are mostly delivery focused. Hence, the solution architect must highlight the longer-term operational risks resulting from architecture decisions made during the design. These risks come into play for the organization after the solution is completed and is being used to support the business. I propose using a simple table to track these risks during the design, then promoting the material risks to your organization’s operational risk register. As a positive side-effect, highlighting the risks can be a powerful catalyst for driving better decisions.
The first rule of solution design is “don’t capture your decisions.” Just kidding! Sort of. Your default approach should be to skip documenting any decision that is already clear from the core elements of your design document – the diagrams and other structured sections. But there does come a time when documenting them is essential. Basically, if anyone will be unsure why a decision was made, much analysis went into the decision, or you are making a wrong decision (hopefully due to factors outside your control), you should document the decision. I recommend a simple table capturing the solution architecture decisions and why each landed where they did. If any external analysis was performed and documented already, like solution options analysis, you could link to it from the decision.
Architecture Use Cases
Users provide many use cases and requirements to describe business needs (hopefully!), but only a small subset of those drive solution architecture choices. An architect should identify and document those to (1) validate that the architecture meets the business needs and (2) provide a way to guide users through the architecture using a context they will understand. Cataloging these use cases and providing a walk-through of your architecture diagram for each one does both! Architecture use cases help you ensure the users of your solution are always front and center where they should be.
Often unknowns make it difficult for a solution architect to complete an architecture. You can turn those unknowns into assumptions. For each unknown, push the decision in the most logical direction and state that as your assumption. Assumptions cover both requirement gaps and technical unknowns. To keep it simple, I also use assumptions to cover dependencies: scope I am not designing because I assume some other dependent activity will handle it.
But Wait… There’s More!
Sometimes. But there shouldn’t be. Solution architecture documentation often gets overloaded with every checklist and the kitchen sink: security checklists, non-functional requirement checklists, standards checklists, etc.
I prefer an approach that makes the solution architect responsible for ensuring an architecture complies with all published standards, de facto organizational preferences, and industry best practices. It’s the job, and they can be assisted with design guardrails and, yes, even checklists, but those don’t have to be embedded in the solution architecture document. The risks and decisions sections should capture when the architect could not comply. Those checklists are tools used in creating the design but add that distracting noise I mentioned in my philosophy up above.
So that’s it. Now give that design one more read and delete anything unnecessary!