High Level Solution Design
Want to cut to the chase and download a project cost estimation model you can use right away? You’ll find a link here.
One of the most common activities for a Solution Architect is production of a design document. Most organisations have their own template and there’s more commonality than not between them. In this article we’ll go beyond what is useless coverage of the content headings and focus on tips and techniques for completing these documents efficiently.
truncate
What is a Solution Design?
No, I’m not being sarcastic! It sounds so basic but as I often do let’s ensure we’re all clear from the beginning. My definition of a Solution Design is:
A blueprint which defines how a software system will be implemented. It describes the components, connections, data, security and related elements which provide a high level view of how a technology solution will be implemented.
Now that we’ve covered what may appear to be an obvious point we can focus the rest of this piece on practical tips and strategies for completion. I say this as simply taking the headings of a Solution Design document and discussing them ad-nauseam offers little value.
Who’s interested in its contents?
Let’s work backwards from who wants what out of this document. That’ll start to inform the task list of things we need to get done.
| Who | Interest |
|---|---|
| Project Manager | Governance gateway to progress (financial, technical) |
| Technical Design Authority | Governance approval from various domains. Security, data, infrastructure, Enterprise Architecture etc. Does it meet standards? |
| Analyst | Requirements alignment |
| System owners | Approval of changes proposed to individual systems |
| DevOps | Can the proposed changes be successfully coded / implemented? |
Who validates it meets requirements?
Often nobody! As I put it, the Solution Design could often be a recipe for cookie dough. Enterprise Architecture check for strategic alignment. Are you using common shared services and building things that align with the ‘vision’? Domain experts in data, security and infrastructure check their bits with much the same purpose. I’ve listed a Business Analyst as someone with an interest in the design. So don’t they have the role of checking it meets requirements? In reality, no. They’re often included in the design but I can tell you from experience this generally doesn’t happen. What, now appears an old school method, used to happen is we would have a requirements traceability section / sessions. Objective being, to show physically in the design how a requirement is met. It was a part of the governance process. However for at least the past 10 years that’s not been the case. The key point here is highlighting a real world observation which is I see this as a real gap that’s very common. So don’t be surprised if you find yourself going through a bit of a box ticking exercise. Something that has a veneer of robustness to it, and indeed does from some viewpoints, except the main one that matters. Does it provide a solution to the actual problem it set out to solve?
Design checklist
At the start of most engagements you need to find out what, who and when as regards your obligations. You will be accountable for design approval. You’ll also be responsible for most, if not all, of the design’s production. It used to be that domain specialists such as infrastructure would be responsible for ‘their bit’ of the design. That’s far less common these days. A very clear divide becomes clear as I write this. Producing the design is one thing. Getting it through a Technical Design Authority is another. This topic is focused on the design document itself. I’ll cover the TDA separately but you’ll definitely see overlap.
- Governance - Identify what’s expected of you, how it works, who the signatories are. Usually you’ll have an Intranet or similar guide showing everything the Technical Design Authority wants, when and how.
- Engage people early - Can’t stress this enough. Get some early thoughts together on a solution, find the people who will sign off your design and go speak to them. Start with a 15 minute intro on who you are, what you’re trying to achieve and how you think you’ll do it. Nothing formal. Be economical with time and precise with your thinking.
- Put everything you know into the design from day 1 - A key measurable objective of your work is the design. Work back from there. Put all your thinking into the document. Flesh out ideas. Iterate. Don’t make the mistake of having material everywhere and think I’ll get around to putting it into the design later. You’ll f**** it up! Be that underestimating the time needed, duplicate effort, miss key parts etc.
- Diarise time with signatories and third parties where necessary - Get slots in the diary to review relevant sections with people. e.g. Validate your designs with them. Be blunt and ask the question of are you happy with this.
Like the sports world. Design approvals are not done at a formal review session. It’s the work you’ve put in before that gets you approval. The formal review should be a formality. You’ve spoken with everyone before hand and gained support before even getting to review.
Design Example
You can download a copy of my design template here. There’s little value in going through it section by section in this guide. You’ll find comments within the document providing guidance on each area. There are definitely tips and techniques you can use to ensure you efficiently complete each section. The document itself will cover that. What I’ll say is once you’ve seen literally dozens of these you’ll find they are all much the same.
Key Takeaways
Speak to people - Find out who has a seat at the design approval table and go speak to them.
Start early - Use the design document as your scratchpad. Start filling out content as early as you can. Iterate it over time.
Don’t blindside readers - Show people things early and get them on the journey with you. Nothing annoys people more than being left out or seeing something late. This begins to touch more on Technical Design Authority topic.
Related topics
- Design Governance - TODO