Writing a technical spec increases the chances of having a successful project, service, or feature that all stakeholders involved are satisfied with. It decreases the chances of something going horribly wrong during implementation and even after you’ve launched your product.
As a software engineer, your primary role is to solve technical problems. Your first impulse may be to immediately jump straight into writing code. But that can be a terrible idea if you haven’t thought through your solution.
You can think through difficult technical problems by writing a technical spec. Writing one can be frustrating if you feel like you’re not a good writer. You may even think that it’s an unnecessary chore. But writing a technical spec increases the chances of having a successful project, service, or feature that all stakeholders involved are satisfied with. It decreases the chances of something going horribly wrong during implementation and even after you’ve launched your product.
In this article, I’ll walk you through how to write a technical spec that ensures a strong product.
A technical specification document outlines how you’re going to address a technical problem by designing and building a solution for it. It’s sometimes also referred to as a technical design document, a software design document, or an engineering design document. It’s often written by the engineer who will build the solution or be the point person during implementation, but for larger projects, it can be written by technical leads, project leads, or senior engineers. These documents show the engineer’s team and other stakeholders what the design, work involved, impact, and timeline of a feature, project, program, or service will be.
Technical specs have immense benefits to everyone involved in a project: the engineers who write them, the teams that use them, even the projects that are designed off of them. Here are some reasons why you should write one.
By writing a technical spec, engineers are forced to examine a problem before going straight into code, where they may overlook some aspect of the solution. When you break down, organize, and time box all the work you’ll have to do during the implementation, you get a better view of the scope of the solution. Technical specs, because they are a thorough view of the proposed solution, they also serve as documentation for the project, both for the implementation phase and after, to communicate your accomplishments on the project.
With this well-thought out solution, your technical spec saves you from repeatedly explaining your design to multiple teammates and stakeholders. But nobody’s perfect; your peers and more seasoned engineers may show you new things from them about design, new technologies, engineering practices, alternative solutions, etc. that you may not have come across or thought of before. They may catch exceptional cases of the solution that you may have neglected, reducing your liability. The more eyes you have on your spec, the better.
A technical spec is a straightforward and efficient way to communicate project design ideas between a team and other stakeholders. The whole team can collaboratively solve a problem and create a solution. As more teammates and stakeholders contribute to a spec, it makes them more invested in the project and encourages them to take ownership and responsibility for it. With everyone on the same page, it limits complications that may arise from overlapping work. Newer teammates unfamiliar with the project can onboard themselves and contribute to the implementation earlier.
Investing in a technical spec ultimately results in a superior product. Since the team is aligned and in agreement on what needs to be done through the spec, big projects can progress faster. A spec is essential in managing complexity and preventing scope and feature creep by setting project limits. It sets priorities thereby making sure that only the most impactful and urgent parts of a project go out first.
Post implementation, it helps resolve problems that cropped up within the project, as well as provide insight in retrospectives and postmortems. The best planned specs serve as a great guide for measuring success and return on investment of engineering time.
Gather the existing information in the problem domain before getting started. Read over any product/feature requirements that the product team has produced, as well as technical requirements/standards associated with the project. With this knowledge of the problem history, try to state the problem in detail and brainstorm all kinds of solutions you may think might resolve it. Pick the most reasonable solution out of all the options you have come up with.
Remember that you aren’t alone in this task. Ask an experienced engineer who’s knowledgeable on the problem to be your sounding board. Invite them to a meeting and explain the problem and the solution you picked. Lay out your ideas and thought process and try to persuade them that your solution is the most appropriate. Gather their feedback and ask them to be a reviewer for your technical spec.
Finally, it’s time to actually write the spec. Block off time in your calendar to write the first draft of the technical spec. Usea collaborative document editor that your whole team has access to. Get a technical spec template (see below) and write a rough draft.
There are a wide range of problems being solved by a vast number of companies today. Each organization is distinct and creates its own unique engineering culture. As a result, technical specs may not be standard even within companies, divisions, teams, and even among engineers on the same team. Every solution has different needs and you should tailor your technical spec based on the project. You do not need to include all the sections mentioned below. Select the sections that work for your design and forego the rest.
From my experience, there are seven essential parts of a technical spec: front matter, introduction, solutions, further considerations, success evaluation, work, deliberation, and end matter.
a. Overview, Problem Description, Summary, or Abstract
b. Glossary or Terminology
c. Context or Background
d. Goals or Product and Technical Requirements
e. Non-Goals or Out of Scope
f. Future Goals
g. Assumptions
a. Current or Existing Solution / Design
b. Suggested or Proposed Solution / Design
c. Test Plan
d. Monitoring and Alerting Plan
e. Release / Roll-out and Deployment Plan
f. Rollback Plan
g. Alternate Solutions / Designs
a. Impact on other teams
b. Third-party services and platforms considerations
c. Cost analysis
d. Security considerations
e. Privacy considerations
f. Regional considerations
g. Accessibility considerations
h. Operational considerations
i. Risks
j. Support considerations
a. Impact
b. Metrics
a. Work estimates and timelines
b. Prioritization
c. Milestones
d. Future work
a. Discussion
b. Open Questions
a. Related Work
b. References
c. Acknowledgments
Now that you have a spec written, it’s time to refine it. Go through your draft as if you were an independent reviewer. Ask yourself what parts of the design are unclear and you are uncertain about. Modify your draft to include these issues. Review the draft a second time as if you were tasked to implement the design just based on the technical spec alone. Make sure the spec is a clear enough implementation guideline that the team can work on if you are unavailable. If you have doubts about the solution and would like to test it out just to make sure it works, create a simple prototype to prove your concept.
When you’ve thoroughly reviewed it, send the draft out to your team and the stakeholders. Address all comments, questions, and suggestions as soon as possible. Set deadlines to do this for every issue. Schedule meetings to talk through issues that the team is divided on or is having unusually lengthy discussions about on the document. If the team fails to agree on an issue even after having in-person meetings to hash them out, make the final call on it as the buck stops with you. Request engineers on different teams to review your spec so you can get an outsider’s perspective which will enhance how it comes across to stakeholders not part of the team. Update the document with any changes in the design, schedule, work estimates, scope, etc. even during implementation.
Writing test specs can be an impactful way to guarantee that your project will be successful. A little planning and a little forethought can make the actual implementation of a project a whole lot easier.
