As teams grow, become distributed, and not everyone is able to be involved in every decision, it becomes more important to record what’s happening and why decisions are and were made. From a technical standpoint, Tech Designs are a great way to structure this information and keep around long-term for posterity.
The following is a template that I’ve used and introduced to teams I’ve worked with in the past. This template is a great starting point and not intended to be an end-all do-or-die approach, so take this more as inspiration than anything else.
A short but descriptive title
| Author(s) | @name |
| Stakeholders | @stakeholders |
| Status | Draft / In-Review / Rejected / Approved / Completed |
| Resourcing | N people |
| Timeline | X weeks |
A standard table header helps to easily scan who is involved, making decisions, and what kind of high level thinking is going into this proposed project.
Problem statement
Write a short 1-3 sentence problem statement. This section should be succinct to summarize the problem and call out its severity quickly.
Goals
Your design should have at least one goal that it is aiming to solve. Your goals should be customer-focused and explain how the benefits that your customer should expect after the work from this design is completed.
Note that the term customer here only relates to the “main benefactor” and is not necessarily a user of a website. It could be developers in your organization, a third party system you work with, or someone else entirely.
Non-goals
Sometimes there are specific things that you explicitly will not be solving. Include them here so stakeholders understand that the scope of this design is limited.
Solution
Use this section to provide details on how we will solve the problem stated at the beginning of this document. Be sure to explain how all of the goals previously listed will be met.
While it is important to be detailed and thorough, avoid going too far and actually writing your implementation here. The key is to describe how your solution will work just enough to be able to break it out into tasks, without doing those tasks yet.
Depending on your team’s needs, you may add some more standard sections here like “Security considerations”, “Data privacy”, or “Scalability”.
Alternatives considered
A good technical design also considers alternative approaches and explains why they were not chosen. Ensure to include pros and cons of the alternatives versus the chosen solution. Ideally, this section helps to show that an objective decision is being made.
Open questions
If you’re unsure about anything, list some open questions here. This is a good spot to get extra feedback from reviewers before proceeding to build your solution.