How do you write a technical specification for a project?

Describe who uses the system, what they need to do, the data involved, the rules that apply, the systems it connects to and how you will know it works. Aim for clarity about behaviour, not for choosing the technology; that is the developer’s part.

By Nazar Kashuba · Reviewed

A specification is a shared understanding written down. Its value is in surfacing disagreements and gaps before they become expensive.

What to include

  1. Purpose and users. Who is this for and what problem does it solve?
  2. User journeys. For each kind of user, the steps from start to finish.
  3. Functions. A numbered list of what the system must do, each stated so you can check it later.
  4. Data. The things the system stores (customers, orders, bookings) and what is known about each.
  5. Rules. Prices, limits, who can do what, what happens in unusual cases.
  6. Integrations. Other systems, with documentation links if you have them.
  7. Non-functional needs. Languages, devices, speed, availability, privacy and security expectations.
  8. Out of scope. What you are deliberately not asking for now.
  9. Acceptance. How you will decide a function is done.

How detailed

Detailed enough that two developers would build roughly the same thing, but without dictating internal technical choices. Screens can be sketches; behaviour should be words.

Do not do it alone

Share a draft with the developer early. They will spot missing rules, risks and cheaper alternatives. The specification improves in conversation, and a living document is better than a perfect one written in isolation.

All questions