How to Write Great Tech Specs
A comprehensive guide on writing great Tech Specs (🎁 Includes Template!)
How often has it happened that, just before releasing a new feature for your product, you discovered something wasn't working as expected? Then, upon conducting a more in-depth investigation, you realized that something was entirely overlooked from the beginning, and now your planned feature will be delayed because it needs to be reworked.
I guess you know where I’m coming from.
What’s missing here?
If I were observing this from an external perspective, I would say a thorough initial analysis and a comprehensive Tech Specs document. And this is precisely what we will explore in today's newsletter.
In particular we will cover:
❓ What a Tech Specs Document is, why it's important, and why it can sometimes be challenging to create one
✍️ How to create outstanding Tech Specs
🎁 My Notion system for creating Tech Specs
💡 Tips from both my own experience and the community
Let's get started!
❓What is a Tech Specs Document?
A Tech Specs (Technical Specifications) document, also often called a Design Document, is a detailed description used to outline the technical aspects and functionalities of a product feature, system, or project.
The Importance of Tech Specs
The primary purpose of a Tech Specs document is to provide clear and comprehensive information about technical requirements and guidelines.
This includes:
🎯 Clarity of Vision: Tech Specs provide a clear understanding of what needs to be built, ensuring that everyone on the team is working towards the same goals.
🔗 Better Communication: they serve as a common language between different team members, helping to bridge gaps between technical and non-technical stakeholders.
🚧 Risk Mitigation: detailed specs help identify potential issues early and plan ways to mitigate them.
📈 Efficiency in Development: with a well-defined plan, development will be smoother, as developers have a clear roadmap to follow.
🔍 Quality Assurance: Tech Specs define quality standards, guiding testing to ensure the final product meets all requirements.
Challenges
While creating a Tech Spec Document can seem straightforward, like writing any other piece of documentation, there are numerous challenges that could arise:
🤔 Complexity: these documents need to include a lot of details, which can make them complicated and hard to write.
⏰ Time-Consuming: writing good tech specs takes a lot of time, which can slow down the start of the actual coding work.
👥 Different Needs: different people, like devs, managers, and clients, all need different things from the Tech Specs. It's hard to make a document that works for everyone.
🗣️ Hard to Explain: it's tough to write complex technical stuff in a way that everyone can understand, especially people who aren't tech-savvy.
❓ Uncertainty: early in a project, you might not know everything. Writing specs with too many unknowns can lead to having to change them later.
🤝 Needs Teamwork: creating tech specs needs input from many people, and getting everyone to work together well can be hard.
⚖️ Flexibility vs. Rules: the specs need to be clear but also allow some freedom for the developers. Finding the right balance is tricky.
✅ Clarity: writing clearly and without confusion is tough, especially for complicated projects.
As you might see there are numerous things that could go wrong and this is why it’s fundamental to have a streamlined and consolidated process.
When do I need Tech Specs?
Creating detailed Tech Specs can save time during development by identifying and addressing potential issues when assessing new features or projects in advance.
However, creating Tech Specs can be time-consuming.
So, is it always essential to have them?
The answer depends on the specific context and the level of risk you're willing to accept. Here are some guidelines based on my own experience to consider:
In Large, structured Organizations: if you're part of a big company with multiple teams and a well-established product, Tech Specs are crucial. They ensure alignment across teams and help mitigate a myriad of risks.
For smaller features in Structured Environments: even in structured settings, if you're dealing with smaller features, you can choose a simpler version of Tech Specs. These should involve fewer iterations and less detail, customized to fit the project's size.
In Early-Stage Startups: in a startup environment, where the team is often smaller and more risk is acceptable, you can consider skipping detailed Tech Specs. However, I still recommend creating brief documents outlining new implementations. This can provide guidance and clarity, even in a fast-paced startup culture.
Remember, the goal of Tech Specs is not just to facilitate development but also to ensure that all team members are on the same page, reducing misunderstandings and reworks.
✍️ Crafting the Document
Producing a Tech Spec Document is not a mere exercise of writing, but it’s more a process split in different phases, where multiple actors are involved.
While there’s no single way to approach this process, I see three main phases:
Collect: during this phase all the requirements for the new implementation are collected in the so called Requirements Document. This phase is usually led by product managers or other stakeholders and it’s crucial. Ideally during this phase a design-first approach should be used and initial designs/wireframes should be included in the Requirements Document. The more comprehensive will be the output of this phase, the easier will be the next phase.
Assess: here, the engineering team and stakeholders review requirements for clarity and alignment with potential technical solutions. A live Tech Specs draft is created for documenting findings and proposed solutions, with much of the collaboration happening asynchronously.
Agree: following the output of the previous phase, when the full document is ready, it's time to agree on it and then start the implementation.
Who Should Write Tech Specs?
Writing Tech Specs is not a solo job; it's a joint effort. While it's fundamental to nominate one person responsible for it at the beginning, there could be many actors involved. In my experience, it's important to keep the number of people involved low, which usually means:
Tech Leads or Architects: these are experienced engineers who have a broad understanding of the system and can ensure that the Tech Specs align with the overall architecture and long-term vision of the product.
Product Managers: while they may not write the technical details, product managers often contribute to Tech Specs by ensuring that the specifications align with the product roadmap and customer needs. They can also help define the scope and objectives of the Tech Specs.
Quality Assurance Engineers: involvement of QA Engineers is crucial to ensure that the Tech Specs include necessary details for testing and quality control.
How to Structure the Document
As it often happens in our field, there’s rarely a single way of doing things and this holds true for Tech Specs as well. Furthermore, as we mentioned before, the document's structure will also depend on how in-depth you want to go with your analysis.
In general, based on my experience, a solid structure should include:
Heading: this is where you include all metadata such as the author, the reviewer, the last modification date, status, teams involved, and more.
Project Overview: this section should be concise and provide context for the document's readers. It should touch on the problem statement, goals, and non-goals.
Proposed Solution: in this section, you should describe how the team intends to solve the problem. It's a high-level description of the solution your team plans to adopt.
Alternative Solutions: it's important to list other solutions considered and explain why they were discarded.
Implementation: this is the core of the technical document. Here, you can include all technical details related to the implementation, such as the tech stack, database structure, API specs, diagrams, and more.
Delivery: this section outlines how you intend to roll out the new feature or project. Include details about deployment, potential roll-back plans, test cases, and more.
Success Criteria: measuring the success of a new product feature or project delivery is crucial. In this section, include criteria that could determine this success.
🎁 My Tech Specs Notion Template
For your convenience, I have created a comprehensive Notion system for creating your Tech Spec documents, starting from my template, and keeping track of them.
This is quite similar to what I've used for years and it has worked well for me. Please be aware that it includes a lot of information that, as mentioned before, you may not necessarily need.
