Tech Spec
Fork this template on Google Docs
Healthy engineering organizations make a lot of technical decisions. Many of those decisions impact multiple teams (Frontend, Backend) and functions (Engineering, Product, Customer Success, Finance). It’s normal to either feel like you’re moving too slow (“too many stakeholders in every decision”) or that your reckless pace creates frequent rework as issues are discovered late (“this problem would have been obvious if you’d just talked to Security first”).
Successful organizations make an explicit tradeoff between quick and comprehensive technology decisions, and the Tech Spec is a key tool for documenting and facilitating that tradeoff, along with reviewing your Tech Specs in some sort of Tech Spec Review.
Example tech spec on InfraEng.dev's hosting
As you think through using Tech Specs, remember that while all engineering organizations have a Tech Spec template, the template itself is specific to each organization. Earlier stage companies may find this template too heavy, whereas larger companies may find that it ignores many key topics. As you look at the proposed template, consider if some other alternative formats suggested in Other Tech Spec Formats might be a better starting point, and always remember that the best template is the one that matches your organization’s particular tradeoff between decision velocity and decision quality.
Related Meetings
Other Tech Spec Formats
- Technical Decision-Making and Alignment in a Remote Culture
- Writing Technical Design Docs, Revisited
- Documenting Architecture Decisions
- How to write a better technical design document
- A practical guide to writing technical specs
Other Approaches to Tech Specs
How to Use
- Fork this template on Google Docs
- Determine appropriate authors for the topic. If you’re not sure who might fit, ask around on your team for their suggestions
- Draft a quick set of answers, time boxing to a few hours
- Shop the draft around to stakeholders with the explicit goal of uncovering controversy and concern: what makes folks most uncomfortable when they read the draft?
- Integrate the draft feedback and polish the draft into a completed spec
- Run it through your Tech Spec Review
- Based on the feedback in Tech Spec Review, make a decision on whether to adopt, refine, or throw out the proposal
- Now you’re done!
Tips
At many companies, the Tech Spec format gets overloaded with too many concerns. A project once blew up cloud costs, and now every project has to detail their projections for future cloud costs. Being succesful depends on maintaining a thoughtful balance between navigating and ignoring bureaucracy, and what specifically makes sense for your company will vary a bit. Sometimes you’re better off ignoring some sections.
On the other hand, if you’re leading the process of designing a Tech Spec format, you should push back on folks who try to add too many concerns to the template. It’s far more important that folks are documenting things at all than that they document things comprehensively. Too many requirements means folks will try to avoid writing Tech Specs!
There are many different Tech Spec formats, play around with them to find one that works well for you, whether it’s Stitchfix’s, Amazon’s, Range’s, or something else entirely