In the last post, we worked on moderating stakeholder conflicts, and updated our design accordingly. At this point, I have a design that I feel really confident about. I’m roughly aligned with key stakeholders, and I’m finally ready to start writing.
If you have a good design (you do, if you’ve followed the steps outlined in the first four parts!), you may be tempted to think that this is the easy part. It’s not! A great design will not automatically translate into a good design doc. And all the work you’ve done so far – thinking about the problem space, investigating different options, validating your ideas, discussing concerns – can make it harder to communicate your ideas at the right level. After all, you’ve spent days (maybe weeks? months?) steeped in this world, and the constraints, terminology, tradeoffs, and background all feel obvious. But your goal is to communicate your design to people who are not spun up on what you’re working on, learn from their feedback, and maybe even discover new stakeholders you weren’t aware of.
PHASE FIVE: COMMUNICATING YOUR DESIGN
Wait, what? Didn’t we just spend phase four making sure stakeholders were aligned with your vision? Isn’t this document for people who are already familiar with this effort, or at least on your team?
Sometimes, but usually not. Regardless, I believe that a design is communicated well when an engineer from a different team, with very little context on the topic, can read through it quickly and think, “Yep, this looks good.”
An engineer from a different team, with little context
This means your design needs enough background and explanation that someone who’s not already collaborating with you can still understand what’s going on. You don’t need to rehash terminology that’s common in your product or standard software knowledge – only what’s specific to your effort. After all, not every reader will have been sitting in your meetings, reading the same Slack threads, or aware of all the nuances and historical context surrounding your effort. Your teammates likely have all of this context already, which means they will be able to parse design docs that an architect on a different team can’t easily understand.
This matters more as an organization grows. A design doc is not just for the two or three engineers working most closely on the feature. It is also for nearby teams, for future teammates, for managers and architects who are trying to stay aligned across the organization, and occasionally for your future self six months (or years!) later when you no longer remember why that “obvious” decision was made.
Quickly
It may sound strange to tie the strength of a design doc to how quickly someone can understand it. But good design docs are quick to read, in the same way that:
- Good user experiences don’t require a manual. A user can usually figure them out quickly because they behave roughly as expected and feel consistent with similar products.
- Clean code is easy for another engineer to skim and understand without too much friction. Good modularity, well-named variables, and consistency with the rest of the codebase and standard design principles make it easy to read code and determine the author’s intent.
Design docs are quick to read when they are well-structured, include all the background necessary to understand the problem space and proposed solution, and address most major concerns or questions ahead of time.
This doesn’t mean that design docs are meant to be read quickly. Most engineers read design docs in a fairly deep way, to understand the full picture, think through the edge cases themselves, and mentally test whether the tradeoffs make sense. Individuals who are reading many design docs across teams (architects, managers, leaders) tend to read more quickly with the intention of ensuring cross-team alignment and consistency across the entire product team. Both are very important, and a strong design doc will meet the needs of both audiences.
Return of the VAMP
Let’s bring back a VAMP (from the last section: a very accomplished and masterful person) who hasn’t engaged much with this topic before (they weren’t a consulted stakeholder from the last section), but has recently become interested in your design doc. For context, they’re a busy person, so they’re hoping to review this design in the twenty minutes between two meetings. Here’s how I imagine a VAMP might review your design doc, and how I’d calibrate each section accordingly.
BLUF
First, a VAMP wants to get a quick sense of what the design is about. What problem is being solved? What is the proposed solution? Does this intersect with something they care about? Maybe they just want to make sure the design is directionally aligned with their architectural preferences, and they’re less concerned about the details. This is what the BLUF is for: it offers enough context to decide what level of engagement is needed for this design.
Requirements
The requirements section is more important than people realize. You have probably spent a long time marinating in all the assumptions that have been made. The VAMP is seeing them for the first time, and an unnecessary assumption gets in the way of the whole design. They’ll wonder if the whole design is over-constrained with unjustified assumptions, and therefore building the wrong thing. This is a very important lens for reviewing a design – after all, a bad assumption can lead to a bad design, even if everything else about the design is perfect.
A good requirements section has as few requirements as possible, and is just as carefully considered as the design itself. It shouldn’t be written as an afterthought to the design. Instead, spend time asking yourself: could this be removed? Could it be softened? If not, why not? If the requirement came from someone else, say who owns it. If it needs extra context, add a quick explanation, collapsible block, or link to more information.
Background
A VAMP does not want to struggle through a design document. Parsing pages full of jargon that assume lots of prior contextual knowledge is not fun for anyone. As such, a good background section that contains expandable blocks or links to relevant prior decisions goes a long way to orienting someone. It’s also very helpful to list any terminology that is specific to a niche area, a new product, or a small set of collaborators. This means that the VAMP doesn’t have to go search through ten other places, some of which are probably outdated anyway, just to understand what the design is talking about.
User Context
Your BLUF, background, or requirements should also answer the important question: what does this do for the user or customer? Your VAMP is not necessarily already spun up on the customer value that will be delivered by your work, but they will want to make sure the value is worthwhile (especially compared to the cost of implementation). Sometimes the end user value is obvious, and doesn’t need more than a line of context. Other times, your design may feel technically removed from the end user benefit and require you to intentionally add a section or extra paragraph somewhere to explain this to a reader who’s unaware of the larger context.
Side note: The user and customer may be different, and there may be different personas involved. For example, a design may inconvenience the user but creates a major benefit for the customer organization (like with governance). Your design should call out the impact and value of your proposed work, and how it impacts customers and the various personas involved.
Design Proposal
A design doc is meant to be opinionated. If you present several very different approaches and don’t really have a preference, that means more work needs to happen before the design is published: have more conversations, and spend a little more time thinking on your own. A design doc is not the right place for a group of reviewers to choose between options; it works best when it presents a clear recommendation, supported by the relevant background and tradeoffs. That is also what a VAMP is usually looking for when they engage with your design: a well-reasoned recommendation on how to move forward.
This doesn’t mean that your proposed design must be superior in every way. If two approaches are very close and you only slightly favor one, that is perfectly fine – and worth mentioning. If you believe the alternatives are truly terrible compared to the proposed direction, that’s worth calling out as well.
Being opinionated on designs matters beyond the design doc itself. In a larger company, design docs are often the primary way that engineers from other teams get a feel for how you think about architecture. Maybe you are very detail-oriented, or highly usability-focused. Perhaps you care a lot about simplicity, practicality, or future extensibility. Your design docs are a way to communicate your design tendencies, and that becomes increasingly helpful as your work reaches beyond your team.
Alternatives & Risks
Strong alternatives & risks sections will offer a VAMP the confidence that you’ve thought about the problem space, tradeoffs, and edge cases thoroughly. They’re not aware of how long you’ve been working on the effort, or how many people you’ve talked to, or any of the extra context your teammates are probably aware of. Instead, they’re looking at the alternatives and risks sections to get a feel for the problem complexity, potential problems, and how you’re thinking about it. Most of the time, they’ll feel satisfied reading your great design doc without needing to follow the rest of the design conversations or effort too closely, because it’s clear that it’s in great hands.
Building this confidence is very important to the success of your design and future implementation, and your teammates’ trust in your proposed direction. So how do you go about this? People will feel confident in your design doc if:
- Your alternatives demonstrate awareness of what the obvious or industry standard approach is. If your preferred approach is different, you clearly justify why the tradeoffs are worth it.
- Your alternatives demonstrate awareness of common patterns at Seeq. It’s clear that you’re either opting for consistency or departing for a good reason.
- Your alternatives (and proposed design) clearly list tradeoffs (pros / cons). There are no major risks or tradeoffs missing.
- Your alternatives show an understanding of complexity. This means that the simplest approach is included either as the proposed design or an alternative, with a clear justification of why additional complexity is worthwhile if your proposed design is not the simplest option. Additionally, if your alternatives vary widely in level of complexity, you’ve called that out or included estimates to help clarify the differences in scope.
- Your design calls out edge case behaviors when they impact some alternatives more than others.
- Your alternatives are ordered (from best alternative to worst alternative) or your opinion on each alternative is very clear.
- Your risks are ordered (from biggest risk to lowest priority risk), and the impact of each risk is clearly conveyed.
- Your alternatives section is complete (or, any alternatives that an engineer who is only mildly familiar with the problem would consider within 5-10 minutes of reading your design is represented somewhere).
- Your alternatives are clearly labeled (Approach One, Approach: Database Modification) so that your document will still be clear if your preferred approach changes over time, you re-order your alternatives, or you add alternatives.
Structure
Structure is critical to the readability of your design doc, which is why the design doc template already recommends standard sections (BLUF, Requirements, Design Proposal, Risks, Alternatives). These recommendations are a minimum, not a maximum. They’ll work for small designs, but you will likely need to add additional structure for more complex designs. In practice, this usually means:
- Split up text into subsections instead of including dense blocks of text that are too long. This is particularly true for the Design Proposal section – it’s most at risk for becoming too large.
- Include diagrams, images, or mockups when possible, and particularly when they can clarify an otherwise dense block of text.
- Include collapsible sections for information that only some readers will care about.
How do you become better at writing design docs?
The best way to get better at writing design docs is simply to read a lot of design docs, especially those from people outside your own team. You will start noticing which questions you really wanted an author to answer as part of the design, and which structures or background sections are particularly helpful. It’s not the most exciting activity, but it’s one of the reasons that managers and architects (people who have to read lots of designs outside of their scope of expertise) tend to be better at writing design docs.
Unfortunately, most engineers do not spend that much time reviewing design docs. And many of the design docs that come their way are from teammates, and focus on areas where they already have a significant amount of surrounding context. All of this context makes it easy to internalize a design doc even if it’s not communicated well. This means that you have to be intentional about setting aside time to read designs from other teams and learning from them.
You can also learn a lot about how readable your designs are based on the questions you receive on your design doc. For example, if there are lots of questions about the requirements or background, it’s likely that you didn’t include enough information.
Final thoughts
A well-communicated design doc will orient the reader quickly, show that you’ve thought through the risks and alternatives, and leave the reader with confidence that you know the problem space and are heading in a strong direction. This is an important engineering skill that you can excel at, even if writing does not come naturally to you or your English is not perfect. It all comes down to including the right information at the right level of detail, and structuring your document accordingly.
And that’s it! Good luck with your next design effort!