← All articles

PRODUCT NOTES

How to Write a One-Page Spec Your Developers Can Build From

A simple one-page spec format with a template and short example, so founders and product owners can hand developers clear work and reduce rework.

Many startup problems trace back to the gap between what a founder pictures and what a developer reads. A short, structured spec closes much of that gap. It does not need to be long. One page is enough for most work.

What a good spec does

  • Explains why the work matters, so developers can make small decisions well.
  • States what is in scope and what is not.
  • Describes what done looks like, so it can be checked.
  • Lists open questions before building begins instead of during it.

The one-page structure

  1. Problem. What is going wrong or missing, and for whom?
  2. Outcome. What should be different when this is done, and how will you tell?
  3. Scope. What is included. What is explicitly not included.
  4. How it should behave. The steps a user takes, in plain language.
  5. Acceptance criteria. A checklist the work must meet to count as done.
  6. Edge cases and open questions. What could go wrong, and what is still undecided.
  7. Dependencies and risks. Other work, people or data this relies on.

A template to copy

TITLE:
OWNER:
DATE:

PROBLEM
Who has the problem, and what happens today?

OUTCOME
What changes when this is done? How will we measure it?

SCOPE
In:
Out:

BEHAVIOUR
1. The user ...
2. The system ...

ACCEPTANCE CRITERIA
[ ] ...
[ ] ...

EDGE CASES / OPEN QUESTIONS
- ...

DEPENDENCIES / RISKS
- ...

A short example (illustrative)

Problem: New users who sign up do not receive a confirmation, so some do not know whether signup worked.

Outcome: Every new user sees a confirmation and receives an email. We will check that fewer users contact support asking if signup worked.

Scope: In: confirmation screen, confirmation email. Out: changing the signup form, welcome email series.

Acceptance criteria:

  • After submitting the form, the user sees a confirmation message.
  • An email is sent within one minute of signup.
  • If the email address is invalid, the user sees a clear error.

Open question: Should the email be sent again if the user signs up twice?

Tips that make a difference

  • Write for someone reading it cold. Avoid shorthand only you understand.
  • Start with the problem, not the solution. Developers often find better solutions when they understand the problem.
  • Walk through it together. A 15-minute conversation with the developer before building catches most misunderstandings.
  • Keep it short. If the spec needs more than a page, the work may be too large and should be split.

Make it a habit

Use the same format every time. After a few weeks the team will know where to look for each piece of information, and review gets faster.

More product notes Let’s Talk