-
Notifications
You must be signed in to change notification settings - Fork 0
product spec one pager
One-Pagers (short product specification documents) are an important part of product development. However, crystal clear thinking upfront can often save multiples of that time down the road when you don't have to throw away expensive high fidelity design or production level code.
One-Pagers also allow teams to get on the same page (particularly in distributed, async orgs) before work begins. These documents help clarify the "why" behind the work. It also defines the project's scope before the team builds the software to solve a problem.
A good one-pager sets parameters around what you’re exploring (benefits and results), without outlining exactly how to do it (features).
Here is a format that I like and have used in the past. I think it's helpful to have a consistent format. If it's widely adopted, the team will also find these easier to consume in the future.
Dev name: Date created: Last modified:
Start all project One-Pagers with a short, consistent table so it’s easy to parse.
| Description | One sentence description of the feature |
|---|---|
| Goals | What is the user goal? What is the business goal? |
| Metrics | What will we measure to determine if the project is successful or not? |
| Responsible | Who is the person or team directly responsible for the project? |
| Impact | Simple T-Shirt Size (XS,S,M,L,XL) |
| Effort | Simple T-Shirt Size (XS,S,M,L,XL) |
| Urgency | Is there a hard deadline? |
| Risks | Explicitly list some of the key risks (1-2 things typically) |
Before working on the solution, start by clearly giving the team the context. Define the problem so that everyone on the team understands what we are trying to solve and why we are trying to solve it.
- What is the user or business problem we are trying to solve?
- What is the evidence of this problem (user feedback, data/chart, intuition)?
- Why is this problem a critical problem to solve now?
- How does this problem fit in with our overall company goals?
The most important thing to define in this section is what is in scope and what is not in scope for the first shippable version of the solution (or minimum viable product, MVP).
- Some design exploration and prototyping may be necessary for more complex experimental features. In these cases, it's good to put some guardrails around the prototyping so that the design space is constrained.
- Be practical about the feature scope based on your knowledge of the technical constraints and team capabilities.
- Summarize the user flow for the MVP so that engineers are not designing UX on the fly.
- List all open questions (design or engineering) clearly so that the team is on the same page about things we need to solve through experimentation.
There are always good ideas that don't make the MVP, and it's good to record them to show how the feature could evolve and constrain the first version.
- List out feature enhancements in the rough order that you will come back to later and prioritize.
- Create a task for each additional piece of work and tag it with the feature name to avoid getting lost after implementation.
- When deciding what to prioritize in the future, you can systematically choose between an enhancement for an existing feature and a new one.
Before launching features, there should be a launch plan and checklist. These ensure the checks and balances for QA (testing, performance), event logging, support documents, AB tests, or a staggered rollout.
Although you can choose to include these in more detailed product specs, they are often similar, and I reserve these for more detailed execution documents vs. simple one-pagers.
Don't keep these documents up to date after shipping the first version, as it adds too much overhead. Features evolve during development, and the purpose of this document is to act as a central starting point to get everyone on the same page. The source of truth usually moves to whatever product/project management tool you use for your roadmap.
Good one-pagers are powerful. Lazy one-pagers are piece of paper. Here’s how you ensure you write a powerful one-pager.
Focus your one-pager on a customer outcome, not a team output. For example, “allow customers to build a relationship with their customers post-purchase” vs. “enable automated follow-up emails.” As a general rule, don’t mention any features. Remember, you’re not writing a spec.
Choose only one outcome, and make sure it’s a compelling one. A compelling outcome is valuable to both the customer (it solves a painful problem in the desired way) and the business (it positively impacts a key metric).
One pagers are primarily for your team. Make sure the information you include is accessible; anyone in the company, technical or not, should understand it.
Aim for one page of easily consumed, inspiring information.
Customers give the best customer context. Wherever possible, use customer data: actual quotes, screenshots of customer conversations, or graphs of customer findings.
Outline a specific product hypothesis your team can test and quantify. If they can’t test it, it’s not a hypothesis.
Great one-pagers center your team around why. As in, “why are we doing this?” They also prompt hard questions, equip your team to challenge your assumptions, and encourage creative solutions.
A good one-pager is a living document that sticks with your team throughout testing and execution. Set a timeline for measuring your success metrics and revisit those often. You also want to update the one-pager whenever you uncover new data for the customer challenge and background context.
And remember, shipping isn’t the end goal; learning is. If you want to make the best bet possible, learn fast and do your research. As Bernadette Jiwa said, “whoever gets closest to their customer wins.”