# How to write a product spec your team will read

> A good product spec is short, specific and honest about what is not decided. Learn how to write one, what to leave out and how to keep it current.

A product spec is only useful if people read it and trust it. Keep it short, make every line testable and keep it next to the work it describes.

Web page: https://kansohq.app/guides/how-to-write-a-product-spec

Updated: 5 October 2026

## Start with the reader

A product spec has three kinds of reader: engineers who will build from it, designers and testers who will check the result against it, and everyone else who needs to know what is coming. Write for the first group and make sure the second can use it. The third will read the first paragraph.

So the first paragraph has to carry the whole idea: the problem, who has it and what changes for them. If a reader stops there, they should still know what the feature is for.

## The parts of a good spec

- **Outcome:** what is true after this ships that is not true now.
- **Core flow:** the main path, as steps a person takes and what the product does in response.
- **Edge cases:** empty states, errors, offline, very large input, someone without permission.
- **Success signal:** how you will know it worked, in one measurable thing.
- **Not doing:** what you decided to leave out, and why.
- **Open questions:** what is still undecided and who decides.

## Write it so it can be tested

Every requirement should be a line that is either true or false when someone checks it. “The page loads quickly” cannot fail. “The page shows content within two seconds on a typical mobile connection” can.

| Vague | Testable |
| --- | --- |
| The form is easy to use | A new user can finish the form in under two minutes without help |
| Handle errors gracefully | If saving fails, the text is kept and a retry button appears |
| Works offline | Edits made offline are saved on the device and sent when the connection returns |

## Say what you are not doing

A “not doing” list is the most useful part of a spec and the part most often left out. It stops scope creep by settling arguments in advance, and it tells reviewers that you thought about the things they are about to suggest.

## Keep it next to the work

A spec in one tool and the tasks in another drift apart within a week. Keep the spec in the same place as the board, link each to-do to its card, and change the spec when the plan changes. A spec that is updated is trusted. One that is not is ignored.

## Review it before building

Ask for review from one engineer, one designer or tester and the person who owns the product decision. Give them a deadline, and ask a specific question: “What is missing?” is better than “Thoughts?”. Record decisions in the spec itself so the next reader does not have to find the thread.

## A worked example

Here is a short spec for a small feature, written the way the parts above ask for. It would take about one page.

**Spec: remember the last board you looked at**

> **Outcome:** opening a project takes you back to the board you were on, not to the project’s first page.
> **Core flow:** the person leaves a board and closes the app. Next time they open the project, the board is shown again, scrolled to where they were.
> **Edge cases:** if the board was deleted, open the project’s first page. If the person has no access any more, show the first page they can see. On a new device, there is nothing to remember, so open the first page.
> **Success signal:** fewer people use the sidebar to find the same board twice in a row.
> **Not doing:** remembering the scroll position inside very long boards, for now.
> **Open question:** should each person remember their own place, or the whole team’s? Owner: product lead.

## Questions reviewers will ask

- What happens when this fails halfway?
- What does someone with no permission see?
- What happens with a hundred of these, or none?
- How will we know it worked, and when will we look?
- What are we not doing, and is anyone expecting it?

If the spec already answers these, the review is quick. If it does not, the questions are the review.

## When a spec has grown too long

If a spec runs past three pages, it usually contains more than one decision. Split it into one spec per feature and put a short overview page above them. Each small spec is easier to review, easier to estimate and easier to keep correct. Do not split a spec just to look short: a single clear page about a hard feature is fine.

## A product spec in Kanso

Open a new page from the [feature spec template](https://kansohq.app/templates/feature-spec.md) or the [product spec template](https://kansohq.app/templates/product-spec.md). Use the slash menu for headings, to-dos, tables and code; turn the to-dos into cards on the [board](https://kansohq.app/product/boards.md); and share the page read-only for review. See [Kanso Docs](https://kansohq.app/product/docs.md).

## Questions

### How long should a product spec be?

One page for a small feature, up to three for a large one. If it needs more, split the work into smaller features, each with its own spec.

### What should a product spec include?

The outcome, the core flow, edge cases, a success signal, a list of what is not being done and the open questions. Add a data model or a sketch only if it helps the reader.

### How is a product spec different from a PRD?

They are close to the same thing. A PRD often covers a whole product or large feature and the reasons for it; a spec often goes into the behavior of one feature in detail. Many teams use one document and one name.

### Where should a product spec live?

Next to the tasks it creates, so the two stay in step. A spec kept in a separate tool is usually out of date within a week.

## Keep reading

- [What is a PRD? How to write one, step by step](https://kansohq.app/guides/what-is-a-prd.md): A PRD is a product requirements document. Learn what goes in one, how long it should be, how to write it step by step and the mistakes to avoid.
- [How to write acceptance criteria, with examples](https://kansohq.app/guides/how-to-write-acceptance-criteria.md): Acceptance criteria say when a task is done. Learn how to write them as clear true-or-false lines, with examples and a checklist for software teams.
- [Definition of done vs acceptance criteria](https://kansohq.app/guides/definition-of-done.md): A definition of done is a team-wide checklist every task must meet. Learn how it differs from acceptance criteria, with an example list to adapt.
- [Feature spec template with acceptance criteria | Kanso](https://kansohq.app/templates/feature-spec.md): A feature spec template with how it behaves, acceptance criteria, edge cases and what you are not doing. Copy it, or start it as a page in Kanso.
- [PRD template: a free product spec to copy | Kanso](https://kansohq.app/templates/product-spec.md): A free PRD template for software teams: problem, solution, who it is for, scope, success measure and open questions. Copy it, or start it in Kanso.

## Parts of Kanso used

- [Kanso Docs](https://kansohq.app/product/docs.md): Pages with headings, to-dos, tables and code, kept inside the project they describe, next to its board and its release.
- [Kanso Boards](https://kansohq.app/product/boards.md): A board for each piece of work. Cards carry a priority, an owner, a due date and the criteria that say when they are done.

[Kanso home, with plans and prices](https://kansohq.app/index.md)