Product spec template: what to include, with an example
Private beta. Access is by waitlist, and paid plans open when the beta ends. Join the waitlist.
A product spec is useful when people can find what they need in it quickly. A template makes that dependable. Below are the sections most teams need and what belongs in each, followed by a complete worked example for a fictional feature.
Header
Product, owner, status and version. The owner is a role or team, such as "Billing product manager", so the spec still points somewhere after a person changes jobs. Status is one of Draft, In review or Approved.
Summary
Two or three sentences: what you are building and what changes for the user. If someone reads only this, they should still know what the spec is about and whether it concerns them.
Problem
What is going wrong today, and for whom. Describe the situation the user is in, with specifics such as the screen they use and the step where it breaks. Leave the solution out of this section.
Goals and non-goals
Goals say what success looks like, in terms a user would recognize. Non-goals say what you are deliberately not doing in this spec. Writing non-goals early prevents most scope arguments later.
Requirements
A table with an ID, one requirement per row and a priority. A common scale is Must, Should and Could. Must means the release does not ship without it. Should means it goes in unless there is a clear reason not to. Could means it goes in if the work fits. Each row should be something a tester can mark as pass or fail.
Success metrics
Measurable and time-bound. A good metric has a target, a time frame counted from release, and a named source. If you cannot measure it, say how you will find out. "Users like it" is not a metric.
Open questions
Things you need an answer to before or during the build, each with an owner. A visible list is better than hidden doubts.
Release plan
How the feature reaches users: internal use, a limited beta, general availability. Each stage needs a condition for moving on, written so you can check it.
Worked example: saved searches
The example below fills in the template for a fictional feature. Tallybird, the invoicing app, is made up, and so are the numbers, targets and roles.
- Product: Tallybird invoicing app (fictional)
- Feature: Saved searches
- Owner: Product manager, billing team
- Status: In review
- Version: 0.3
Summary. Saved searches let a user store a set of invoice list filters under a name, such as "Overdue, Client North", and reopen it from the sidebar in one click. Results are fetched each time a saved search is opened, so invoices created after saving show up. Each user can keep up to 20 saved searches.
Problem. Users who check overdue invoices each week rebuild the same three filters (status, client and date range) every time. Nothing in the invoice list remembers them. A user who leaves out one filter sees a different list without noticing.
Goals.
- A user can save the current invoice list filters and reopen them later from the sidebar.
- A saved search always shows current invoices, not a snapshot from the day it was saved.
Non-goals.
- Sharing a saved search with other users. This spec covers personal searches only.
- Saved searches for reports, customers or payments.
- Scheduled email digests of a saved search.
- Any change to how the invoice filters themselves work.
Requirements. Each row is one decision.
| ID | Requirement | Priority |
|---|---|---|
| SRCH-1 | A user can save the current invoice list filters under a name of 1 to 40 characters. | Must |
| SRCH-2 | A user can open any saved search from the sidebar with one click, and the invoice list shows its saved filters applied. | Must |
| SRCH-3 | Results for a saved search are fetched when it is opened, so an invoice created after saving appears in the results. | Must |
| SRCH-4 | A user can rename or delete their own saved searches. Deleting asks for confirmation in a dialog with a Delete button. | Must |
| SRCH-5 | A user can keep up to 20 saved searches. Saving a 21st shows the message "You have 20 saved searches. Delete one to save another." and saves nothing. | Must |
| SRCH-6 | A saved search is visible only to the user who created it. A request for another user's saved search returns a 404 response. | Must |
| SRCH-7 | A user can pin up to 3 saved searches so they sort above the others in the sidebar. A fourth pin shows a message and does not pin. | Should |
| SRCH-8 | If a saved search filters on a client that has been archived, the search still opens, shows a notice naming the archived client, and applies its other filters. | Could |
Success metrics.
- Within 8 weeks of general availability, at least 30% of users who view the invoice list in a given week also open a saved search that week. Source: weekly count of the analytics event saved_search_opened, divided by weekly users who view the invoice list.
- Within 12 weeks of general availability, the help desk tag "repeat filter" appears on 10 or fewer tickets per month, down from 40 in the month before release. Source: the monthly help desk export.
- Under 0.5% of saved search opens return a server error in the 4 weeks after general availability. Source: the server error log, filtered to the saved search endpoint.
Open questions.
- Should archived invoices appear in saved search results by default? Owner: billing lead.
- Is 20 the right limit for saved searches, or do large accounts need more? Owner: product manager, after reviewing beta support tickets.
- Does the sidebar need a search box once a user has more than 10 saved searches? Owner: design lead.
- Should the saved_search_opened event also record how many filters were applied? Owner: data engineer.
Release plan.
- Internal use. The team uses saved searches on its own test account for two weeks. Move on when no open bug is rated Critical and every Must requirement passes the test script.
- Limited beta. Up to 15 customer accounts turn the feature on through a feature flag. Move on after 4 weeks with no reports of missing invoices in results and an error rate under 0.5%.
- General availability. Every account can use saved searches. The help article is ready before the switch.
Vague vs testable
A requirement is testable when a tester can run a check and get a clear pass or fail.
| Vague requirement | Testable rewrite |
|---|---|
| Saved searches should load quickly. | The first 50 results appear within 2 seconds at the 95th percentile for an account with 10,000 invoices, measured over 20 runs on the staging test account. |
| Users should be able to manage their searches. | A user can rename or delete any saved search they own from its sidebar menu in 2 clicks or fewer, and a deleted search is gone after a page reload. |
| The filter labels should be easy to understand. | Each applied filter shows as a label in the form "Field: value", such as "Status: Overdue". A tester can match every label to a field name in the filter list of the spec. |
| Other users' data should stay private. | A request for a saved search that belongs to another user returns a 404 response, checked by an automated test on each saved search endpoint. |
How much template to use
Match the template to the size of the change.
- Small change, such as a label, a default value or a copy fix: a header, a summary and one requirement row. Skip the metrics, the open questions and the release plan.
- Medium change, such as a new option on an existing screen: every section, kept short.
- Large feature, such as a new area of the product or a change to stored data: every section in full, with a metric source and a condition on every release stage.
Some parts are never skipped, whatever the size: the owner and version in the header, the non-goals, a priority on every requirement, and an owner on every open question. Those are the parts reviewers ask about first.
The SaaS product spec sample on the home page follows this layout with a fictional "Snooze and Reminders" feature. In Wordspecs, the same sections are a template, so every spec your team writes has them in the same order.
Related: saving your own spec-sheet templates.