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
- Problem. What is going wrong or missing, and for whom?
- Outcome. What should be different when this is done, and how will you tell?
- Scope. What is included. What is explicitly not included.
- How it should behave. The steps a user takes, in plain language.
- Acceptance criteria. A checklist the work must meet to count as done.
- Edge cases and open questions. What could go wrong, and what is still undecided.
- 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.