It can feel daunting to write a technical spec. It can feel like too much hard work, or worse, busy work that’s not really important.
But writing a design doc doesn’t need to take a lot of time and ideally saves you time in the future. You don’t even need to know what you are going to do before starting, as writing a design doc can be a great exercise in “thinking through writing”. In this article, I walk through the purpose of a technical design document, the elements of an effective tech spec, and some specific thoughts and examples to help you improve alignment on your team.
What is the purpose of a technical design document?
The purpose of a technical design document is to aid in the critical analysis of a problem and the proposed solution, while also communicating priority, effort, and impact with various stakeholders.
A good design doc will preempt questions and queries that might arise during the code review process, identify edge-cases, and will allow people to suggest improvements before a lot of work has been done.
Note: If a design doc proves controversial that’s a great signal that an in-person discussion should be had or that the problem isn’t well defined.
Download the free Engineering Manager's eBook of Team Questions
Here's a template for your next design document
Starting with a blank canvas is difficult. I’ve found that a good template can speed up the writing process and prompt you to think through important areas that may not be top of mind.
Each section in this article mirrors a section in your design document, it’s a variation on the technical documents I wrote at Google and brought to the engineering team at Medium. You may find that some sections aren’t relevant to all teams and projects, so use what is helpful and drop the rest.
The ultimate goal of a design document is to facilitate communication and alignment, not to create unnecessary bureaucracy.
Overview
Start at the beginning. What problem are you trying to solve? If you jump straight into solutions, it will be hard for people to orient themselves and will inevitably lead to misalignment and misunderstanding. It’s worth spending 2 or 3 sentences effectively setting the context for your spec.
Then, briefly state your proposed solution. This should be enough for most people to decide whether they should continue reading and should be understandable by someone who is not familiar with the project. Between a few sentences and two paragraphs should be enough.
Background
It’s unlikely that writing the design document is the first time you’ve thought about the problem. The background section is an opportunity to bring readers up to speed, and share the context you have on the problem space.
What are the motivations for the project or design? Is there any historical perspective that will help people understand the proposal? Has someone tried to solve the problem in the past? If so, why are those solutions no longer appropriate? Are there any other things going on that will affect the design?
Goals, non-goals, and future goals
In order to build alignment and communicate a definition of done, it is important to clearly articulate the goals of this work. The best goals are simple, truthy sentences that describe a future state of the world. Unlike an OKR, it’s fine for these goals to be hyper-specific.
Projects will often have 3-5 goals.
Examples:
- Hot backups are available in 3 regions
- Deactivated accounts have their data automatically purged after 30 days
- Web UI uses React instead of Vue
- Mobile clients receive automatic updates
Non-goals
As well as explaining what you want to achieve, it is equally important to say what you are explicitly not addressing. These can sometimes be hard to identify, but imagine what another person might expect to be coupled with this work.
Leadership tip: Understanding the interconnectedness of work is an important task for engineering teams — and all teams, for that matter. We chatted with Pat Kua, a seasoned engineering leader and founder of Tech Lead Academy, who shared, "I often just encourage people to create a visual model of like, what are these connections? It's often very useful to say, okay, these things affect each other, these have these results, and you end up building a web of interesting interconnection."
For more insights, check out our full Lead Time Chat with Pat Kua on different styles of tech leadership.
Future goals
Future goals are an opportunity to list things you want to do in the future but have descoped for this phase of the project. In other words, these are things you want to make sure your solution doesn’t accidentally make difficult or impossible.
Detailed design
This is the meat of the technical documentation and also the most variable. Depending on the project, the size of your team, or number of stakeholders, it may be a few paragraphs or a few pages. It will often contain pseudo-code, schema definitions, or flow diagrams.
Here are some common questions that get answered as part of the detailed design:
- What are the user requirements?
- What systems will be affected?
- What new data structures are needed, what data structures will be changed?
- What new APIs will be needed, what APIs will be changed?
- What are the efficiency considerations (time/space)?
- What are the expected access patterns (load/throughput)?
- How will data be validated and what are the potential error states?
- Are there any logging, monitoring, or observability needs?
- Are there any security considerations?
- Are there any privacy considerations?
- Are there any mobile considerations?
- Are there any web-specific considerations?
- How will the changes be tested?
- How does internationalization and localization — translations, time zones, unicode, etc. — affect your solution?
(You probably don't need to answer all of them.)
Third-party considerations
Today it is common to rely on third-party platforms to support our development work, whether this be part of AWS or GCP, or a whole separate service. It’s worth thinking through the implications of using a third-party and looking ahead for potential future issues.
The cost of these services is often less than an engineer’s time, but sometimes it can scale unexpectedly. Quickly think through how the service is billed and do a back-of-the-envelope calculation of what could be expected once the service is fully rolled out.
While security and privacy considerations were addressed in the detailed design, when using a 3rd party there are specific things to think about and call out.
For example, if the third-party is being used to perform operations on customer data they will likely be considered a subprocessor under the EU’s General Data Protection Regulation (GDPR). So, do you need a data processing addendum? Do you need to collect and review SOC2 reports? Sometimes customers will require notification of new subprocessors, which will affect the roll-out plan below.
Work estimates
For non-trivial changes, provide a breakdown of the work and tasks. How long will each phase take? What work is parallelizable? What dependencies on other teams are there?
Roll-out plan
It’s unusual that you can roll out your project as a single change. In this section, discuss how changes to models and APIs will need to be staged. Will you be rolling out incrementally to your users using feature flags?
Discuss your revert path. If something goes wrong, how will you back out partway through the process while leaving systems in a healthy state? Identify the biggest risks you see, and spell out how you’ll detect and mitigate them.
Alternative approaches
It’s not enough just to share your chosen solution. By explaining approaches that you rejected you can reduce time handling objections from other stakeholders and focus the discussion on your chosen design. Make sure to explain why other approaches seemed inferior or wouldn’t work.
It’s also not unusual for information to emerge during the design process that escalates an alternative approach to the primary approach. If this happens, try and avoid the sunk cost fallacy.
Related work
Are there products — internal or external — that are similar to this project? Are other teams being faced with similar challenges?
As an example, if you are building your own NoSQL database (😱) this section might include a feature matrix comparing your technical requirements to existing database offerings.
Future work
This is where you can help prevent bike-shedding and scope creep. Identify anything you’re not addressing with this particular design but that should happen in the future or that would be a logical follow-on project? This is often a more detailed description of the future goals, or perhaps how some of the non-goals might be addressed in the future.
When you’ve written your first draft, go back and reread it. Question each statement and decision. If the reasoning is not clear, add more clarification.
Wrapping up
I’ve seen this template help software engineers of all levels — I even used it to help me think through a solution to a data analysis problem we have here at Range.
I’ve also seen people react negatively to the idea of technical design docs, and to be fair, for many teams and environments, a lot of projects don’t really need technical documentation. Unfortunately, there’s no hard and fast rule on when a spec is appropriate. It’s a function of complexity, certainty, and risk, and is something you’ll have to feel out for yourself.
But, next time you’re working on a gnarly problem, or juggling multiple stakeholders, try using this template, and let me know how it goes.
You can find me on Twitter @dpup.
Learn More with Lead Time
Lead Time Chats are unscripted conversations with engineering leaders and other influential folks in tech, hosted by Jean Hsu (engineering leadership coach and VP of Engineering at Range).
You can explore past episodes any time on the Range blog to learn best practices for keeping your team productive and connected.
For tech leaders looking for insights and strategies to support them in building and leading effective teams, we also offer a Lead Time newsletter. Sign up today and get useful insights delivered right to your inbox.
Continue with Google
Continue with Slack
Continue with Microsoft
