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

Future Goals

  • what we want to leave open as a possibility in the future.


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

Preferred Implementation

How you are going to build it.

  • data modelling

Rejected Alternatives

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.

Estimated Effort

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


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

Ex-gaijin, kangaroo-loving software simian from Merrie England, building @Mailchimp and @Pinian. Formerly @Medium and @StumbleUpon.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store