Technical Specs

Jamie Talbot
Jan 30, 2018 · Unlisted

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 :)

Context

  • short description, ideally referencing a product spec.

Goals

  • what we want to achieve now
  • simple bullet points.

Future Goals

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

Non-goals

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

Preferred Implementation

How you are going to build it.

  • data modelling
  • validation
  • endpoint definition / API signatures / payloads
  • FE components
  • authorisation
  • project-specific implementation details
  • etc.

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
  • expected time to implement

Risks

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

Deployment

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

Unlisted

Written by

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

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade