Design context is more important than a detailed solution
We will never have enough information before implementation to be able to design a perfect solution. Inevitably, what we know will change as we implement.
With a software design, having enough context is more important than having a detailed solution.
We will never have enough information before implementation to be able to design a perfect solution. Inevitably, what we know will change as we implement.
We learn from the implementation done so far. Outside factors change requirements, schedules, or resources. A detailed design is too rigid to allow the team to adapt to changes.
Too much up-front design-decision slows projects down. It limits the flexibility of the people implementing it. I prefer lightweight design processes that enable autonomy. We want just enough information for stakeholders to move forward.
We don't need a perfect solution — only a good enough one.
We don't need a detailed solution — only just enough of one.
A solution direction is better than a solution destination. If the team understands the problem, they can pivot as much as needed to deliver a good enough solution. So, providing just enough context is crucial to enabling autonomy. Leave the details for later — for the last responsible moment.
So then, what is just enough context? Let's dig into the details.
Why do we need a design document anyway?
A Design Document describes the context of a problem, the outcome expectations, and the solution to address it.
Its purpose is to:
Get alignment on business needs.
Provide a solution that will satisfy those needs.
Inform those impacted.
Guide those who will implement it.
It is the rallying point for all technical discussions around a problem.
It should only be extensive enough to meet the team's needs — no more, no less.
Who figures out all this context?
The engineers close to the problem drive the design — they are the "Driver". Not product. Not architects. Everyone supports and collaborates with the Driver.
In DACI terms, the Driver is the person who moves the project forward and is responsible for the decision-making process. (For more on what it means to be the Driver, see Driving software design forward)
So, the Driver figures out the context.
Who is all this context for?
The goal is that you can hand the document to anyone with the required experience on your team, and they can implement the solution without your further input.
The more context you can provide, the better they will understand the problem and how your solution addresses it. The more they understand the problem, the more capable they'll be of adapting the solution direction to changing demands.
Who needs this context depends on the particular problem that a solution is being designed for. Depending on the scope of the problem, the audience can include:
Product team
Security, Privacy, or Compliance teams
Architects
Engineering managers
Operations, Platform, or Infrastructure teams
Quality Assurance
Implementing engineers
You are writing for the audience. Consider who your audience is when designing. Anticipate the audience's questions and answer them in the document before they have to ask. Make it easy for them to see that you understand the problem and that your solution addresses it.
Yes, but how much context is that?
Keep in mind that readers have a limited context window. For designs, the context window is everything they know about the products within the organization. Everyone's context window overlaps with each other's at different points. You can only address so much context, so your document itself has a limited context window.
The document's context window is a sliding window that falls somewhere between high-level business information and low-level implementation details.
Put the most relevant and urgent information in the design context. Then, go a step further and widen the window slightly to the left to give engineers hints of where to go for more business information. Much of the document will go into implementation details, so there is usually no need to widen the context window further to the right.
One way to provide additional context, especially if you're feeling lazy efficient, is to provide links. Everyone can use the links as a breadcrumb to find more relevance. The links also bind related information together through backlinks. Future developers, including future you, will thank you for these links.
Isn't that a lot of work?
The challenge is to figure out what information will drive the design in a good direction and well inform the people implementing it.
All this might sound like I suggest you design every function call and write pseudo code. I am emphatically not. The document should stay high-level and leave low-level implementation details up to the team who will implement it.
Convey just enough context so the people implementing it understand enough to have autonomy. Then, they can make micro-decisions while satisfying the organization's needs.
The amount of context you need to provide is proportional to the complexity and impact of the problem you are solving.
More complexity = more context
Involves multiple internal teams = more context
Huge impact on customers = more context
Affects many services = more context
If you are designing a simple solution to a problem that only affects your team, then the context and document should be relatively small.
If you are designing something that affects a lot of teams or has a huge business impact, then you will need to provide enough context to inform those affected and convey that impact.
What context is valuable?
Current state and how it falls short of the business need
Problem description, particularly user or business pain points
Why this change needs doing from a business perspective
Level 1 or 2 C4 Model diagrams
Use cases that explain goals a user should achieve using the system
You might notice an emphasis on "business." Business impact is the most crucial consideration of a design. If it does not satisfy the needs of the business, what is the point?
If someone can't convey business needs and impact or they are not well understood, the design's fitness can not be judged. If it can't be judged fit, the design, its context, or the project should be reconsidered.
Understanding the business needs and the impact of a change is a key motivator and grantor of autonomy for the team. It enables them to take pride in ownership.
With enough context, the team can make sound decisions when adapting to changing demands.
For more details on design, see:
You mentioned Levels 1 and 2 from C4, do you consider using tools like Structurizr for demonstrating/documenting the Context or you never found it useful?