When writing tech specs, I usually include most of these sections, in this order. I’ve found that doing specs in this way often heads off questions from others, clarifies the work to come, and allows me to break up the problem into smaller tasks that multiple people can work on simultaneously. I find a good spec lets me come back to it like a recipe and implement the work without doing too much extra thought as I’m writing the code.
Not all projects need all these sections, but most of them need most of them :)
- short description, ideally referencing a product spec.
- what we want to achieve now
- simple bullet points.
- what we want to leave open as a possibility in the future.
- simple bullet points.
The most important part of the spec — your design may preclude some future possibilities, possibly for the sake of simplicity, or pragmatism. You have to state what will never be supported, and make that clear to everyone involved.
- what we don’t care about achieving, and the design does not address
- simple bullet points
How you are going to build it.
- data modelling
- endpoint definition / API signatures / payloads
- FE components
- project-specific implementation details
The second most important section — this helps sharpen your thinking around your preferred approach, and ensures you’ve thought deeply about the problem.
- at least one alternative way of doing this, and why that approach is not a good idea. Preferably two alternatives.
This section forces you to think about how to break up the work and the interim deliverables, and helps you keep your Pull Requests small so they can be reviewed in a timely manner.
- rough number of patches to implement, in a rough order
- expected time to implement
Lots of things can go wrong. What are the risks? Will it be possible to undo a data migration if it goes wrong? Will there be unexpected load on a table that can cause issues? Are you using an unproven or new technology? Will a change in scope dramatically extend the timeline?
- what could go wrong
This section forces you to think about ultimate delivery of the feature to the end-user. Is it just going to be turned on for 100% of people? Or a small trial group first? Is it behind a variant or feature flag? Do you require deployment of multiple systems that need to be coordinated in order to avoid race conditions or inconsistent state?
- how we will deploy