The Document Most PMs Write Wrong
The Product Requirements Document (PRD) is the most common writing artifact a PM produces. It is also one of the most frequently done badly. PRDs that nobody reads. PRDs that try to specify every detail and end up being out of date before anyone opens them. PRDs that miss the most important questions while listing every minor one. PRDs that read like contracts and produce defensive engineering as a result.
When PRDs work, they are one of the highest-leverage things a PM writes. They align the team. They surface questions early. They produce shared understanding before code is written. When they don't work, they are a tax on everyone involved: time spent writing, time spent reading, and time spent re-writing because the document drifted from reality.
This article is about writing PRDs that actually work. We will cover what should go in them, what should be left out, how the modern PRD differs from the old waterfall version, and the simple discipline of keeping the document focused and current.
What a PRD Is For
A PRD has three jobs. Done well, it does all three. Done badly, it tries to do other things instead and fails at all of them.
Job One: Align the Team
Engineering, design, and PM should share an understanding of what is being built and why. The PRD is the artifact that captures that shared understanding. Without it, each person builds their own mental model, and the models diverge in ways that surface as conflicts during the build.
Job Two: Surface Questions Early
Writing a PRD forces you to confront questions you might otherwise avoid. What happens in this edge case? Who is the primary user here? What is success? What is out of scope? Many of these questions don't have obvious answers, and the act of writing forces them to be answered before code makes the answers expensive to change.
Job Three: Provide Reference During the Build
When questions arise during implementation (and they always do), the PRD is the reference. What did we decide about this case? The team can look it up rather than ask the PM, who may be in a meeting or on holiday. This reduces friction and keeps engineering moving.
The Old Way and the New Way
Traditional PRDs were long, comprehensive documents that specified every detail before any code was written. They came from the waterfall era, when development cycles were long and the cost of getting it wrong was enormous. Some companies still write PRDs this way, and it usually doesn't work in modern software.
The Old Way
- Long (twenty to fifty pages)
- Comprehensive (every screen, every state, every error message)
- Static (written once, not updated)
- Sequential (PRD finalised before design starts; design finalised before code starts)
- Authored alone (PM writes, others sign off)
The problem: by the time the long PRD is finished, assumptions have shifted. The user research is two months old. The market has moved. The team has new constraints. The PRD specifies a world that no longer exists, and engineering has to choose between following the spec (and shipping the wrong thing) or ignoring it (and making the document irrelevant). Either way, the document fails.
The New Way
- Short (two to five pages for most features)
- Focused (the important decisions, the key flows, the edge cases that matter)
- Living (updated as understanding evolves)
- Iterative (PRD, design, and engineering work in overlapping cycles)
- Collaborative (engineering and design contribute to shaping the PRD; the PM is the editor, not the sole author)
The modern PRD is closer to a working document than a specification. It captures the shared understanding at a given moment. It evolves as the team learns. It does not try to be exhaustive; it tries to be useful.
What Goes In a Modern PRD
Different companies use different templates, but the core elements that show up in good PRDs are similar. Here is a template that has worked for us. Adjust based on context.
1. Summary (One Paragraph)
What is being built, for whom, and why. A reader should be able to understand the entire feature from this paragraph. If the reader stops here, they should know the gist. The summary is the most important part of the document because it is the part most people will read.
2. Problem and Context
What user problem does this solve? Who has the problem? How do we know? What evidence supports this being worth solving? This section grounds the work in user reality. Without it, the team is building a solution without confirming there is a real problem.
3. Goals and Non-Goals
What outcomes are we trying to produce? What metrics will tell us we succeeded? Equally important: what are we explicitly not trying to do? Non-goals prevent scope creep and clarify the focus of the work. This feature does not address X, even though X is related and important. We will address X separately later.
4. Key User Flows
The main paths users will take through the feature. Two or three paths is usually enough; you don't need to specify every possible path. Include what the user is trying to do, the steps they will take, and what success looks like at the end. Designers will produce more detailed flows; the PRD's job is to capture the user-side view.
5. Functional Requirements
What the feature must do. Specific enough to guide design and engineering. Not so specific that you are designing the implementation. Users must be able to share a project with another user via a link. Engineering will decide the data model; design will decide the interaction; the PRD specifies the requirement.
6. Edge Cases and Error States
What happens when things go wrong? When the network is down? When the user enters bad data? When permissions don't match? When two users do conflicting things at the same time? These cases often determine whether the feature feels polished or broken. Skipping them in the PRD pushes the decisions to engineering during implementation, where they are made under deadline pressure with insufficient input.
7. Open Questions
What we haven't decided yet. The questions that are still outstanding, with named owners and target resolution dates. This section is often the most useful part of the document because it tells the team what they don't yet know. Many PRDs hide their gaps; good PRDs surface them.
8. Out of Scope
Specific things that have been considered and explicitly left out. This release does not include team permissions; we are tracking that in a separate initiative. Out-of-scope sections protect against scope creep and clarify what the team is and isn't committing to.
9. Metrics and Success Criteria
How will we know if this worked? What metrics will move? Over what timeframe? Who is responsible for measuring? Without this section, features ship and nobody learns from the launch. With it, the team has a clear definition of success and a plan to measure against it.
10. Dependencies and Risks
What other teams or systems are required for this work to ship? What could go wrong? What assumptions are we making that could be wrong? Surfacing these early prevents nasty surprises later.
What to Leave Out
Some things often appear in PRDs but shouldn't. They make the document longer without making it more useful, and they blur the boundaries between PM, design, and engineering responsibilities.
Detailed Visual Design
The PRD should describe the user-facing requirements, not the visual treatment. Wireframes are sometimes useful for context, but the design itself should live in design files, not in the PRD. PMs who try to specify visual details often produce unworkable designs and frustrate the design team.
Implementation Details
How the feature is built is engineering's call. The PRD describes what should happen from the user's perspective, not the data model, the API design, or the storage approach. When PMs specify implementation, they often do so wrong, and engineering has to either follow the bad spec or have the spec rewritten.
Every Possible State
An exhaustive list of every screen, every interaction, every permutation of options. Some of this lives in the design; most of it doesn't need to be specified at all. Engineers and designers can fill in obvious cases. The PRD specifies the cases where the obvious answer might be wrong.
Marketing and Sales Material
How the feature will be marketed, named, priced, or sold belongs in separate documents. Mixing these into the PRD produces a document that tries to be everything and ends up being nothing useful. Keep the PRD focused on the build; let go-to-market live elsewhere.
Project Management Details
Who is doing what, when, with which dependencies on other tasks. This belongs in your project management tool (Jira, Linear, Asana), not in the PRD. The PRD describes the feature; the project tool tracks the work.
Length and Format
The single biggest improvement most PRDs need is to be shorter. A PRD that is twenty pages will be skimmed at best, ignored at worst. A PRD that is four pages will be read.
A Useful Length Heuristic
Most features should have a PRD between two and five pages. Larger features may need more, but if you are writing fifteen pages, ask whether the feature is really one feature. It may need to be broken into smaller pieces, each with its own shorter PRD.
Format
Most teams use a written document (Google Docs, Notion, Confluence). Some use a different format (long-form notes, engineering tickets with detail, even Figma comments). The format matters less than the discipline of capturing the key decisions in writing. The reason to use a written document is that writing forces clarity in a way that verbal discussion does not. If you can't write it down clearly, you don't yet understand it clearly.
Writing a PRD: A Practical Sequence
Here is the sequence we use most often. It produces useful documents in a few hours rather than days, and the documents are more useful than longer ones because they focus on what matters.
- 1. Start with the problem. Write the problem statement first, before even sketching the solution. If you can't state the problem clearly in two sentences, you don't yet understand it well enough to write the rest.
- 2. State the goals. What are we trying to accomplish? What measures will tell us we did? Be specific.
- 3. Sketch the key flows. Walk through what the user will do. Include the moment of value: where the user achieves the thing they came to do.
- 4. List functional requirements. What the feature must do. Stay at the requirement level; don't describe the implementation.
- 5. Surface edge cases. What can go wrong, what is unusual, what is contested? These are often where the real product decisions are.
- 6. Name what is out of scope. What you considered and are not doing this round. This protects the focus of the work.
- 7. Identify open questions. What you don't yet know, who will figure it out, by when. The unanswered questions are the most useful part of the document.
- 8. Share early, share often. Don't finish in isolation. Share the early draft with engineering and design. Their feedback will improve the document. The PRD is collaborative, even though the PM owns the editing.
Living Documents
The biggest mistake teams make is treating the PRD as a one-time deliverable. The PRD is finished, signed off, and filed; engineering goes to work; reality intervenes; the document never gets updated. By the time the feature ships, the PRD describes a feature that no longer exists.
A living PRD is updated as understanding evolves. When a decision changes, update the document. When a new edge case is discovered, add it. When an open question gets resolved, record the answer. The document at the end of the project should describe what was actually built, not what was originally planned.
This requires discipline. PMs who write the PRD, ship the feature, and never look at the document again miss the value of the document as a record. The next person who wants to understand why something was built a particular way needs the answer. A living PRD provides it. A frozen PRD requires asking around in Slack and reconstructing history from memory.
Common Mistakes
Mistake One: Writing for the Wrong Audience
Some PRDs are written for executives who will read the first page. Some for engineers who will read the whole thing. Some for both. The audience matters; trying to please everyone produces a document that pleases nobody. Decide who the primary reader is and write for them, with a summary at the top for the others.
Mistake Two: The Specification Trap
PMs sometimes try to specify every detail to remove ambiguity. The result is a long, rigid document that constrains good engineering and design judgment. Trust your team. Specify what matters; let them figure out the rest.
Mistake Three: The Wishful Thinking PRD
PRDs that describe a feature without honest assessment of complexity, risks, or open questions. Everything seems tractable; everything seems desirable. Reality intervenes during the build, and the document's gaps become engineering's problems. Honest PRDs name the hard parts explicitly.
Mistake Four: Skipping the Review
A PRD shared late, after the PM has finalised it, gets less thoughtful feedback than one shared early. Engineering has context the PM lacks. Design sees usability issues the PM misses. The fix is to share drafts well before they are final, ideally as you are still drafting them.
Mistake Five: Letting the PRD Get Stale
The most common mistake. The PRD is written, the team works from it for two weeks, then it stops reflecting the actual work. Engineering ships from memory and Slack threads. The PRD becomes useless as a reference. The fix is the discipline of updating, even when nothing seems to require it.
Alternative Formats
PRDs are not the only way to document product work. Some alternatives that work well in different contexts:
One-Page Briefs
For small features, a one-page brief is enough. Problem, goal, key flow, success metric. Anything bigger is overkill. The discipline of keeping it to a page forces focus.
Opportunity Briefs
When a feature isn't yet defined, an opportunity brief describes the user problem, the evidence that it matters, and the rough approach being considered. This is pre-PRD; it precedes the decision to invest in solving the problem.
Working Backwards Documents
Popularised by Amazon. Write the press release for the feature before building it. The press release forces clarity about who the feature is for, what it does, and why anyone should care. Useful for early-stage product thinking.
Engineering Design Docs
For technical work, engineering often produces its own design doc covering architecture, data model, and implementation details. The PRD and the design doc are complementary: the PRD covers the user side; the design doc covers the system side. Both should exist for significant work.
A Final Word
PRDs are tools. Their job is to align the team, surface questions, and provide reference. When they do that, they are worth the time. When they don't, they are a tax on everyone. The difference is in length, focus, and currency: shorter than you think, focused on what matters, and updated as the work progresses.
If your PRDs are not currently doing their job, the fix is usually to make them shorter, more focused, and more current. Cut the implementation details. Cut the exhaustive specs. Keep the problem, the goals, the key flows, the edge cases, the open questions, and the out-of-scope. Update them as you go. After a few iterations, the documents will start being read again, and they will start doing the work they were supposed to do.
Key Takeaways
- A PRD has three jobs: align the team, surface questions early, and provide reference during the build. Writing should serve those, not other goals.
- Modern PRDs are short (2 to 5 pages), focused on the important decisions, and updated as understanding evolves.
- Include problem, goals, key flows, requirements, edge cases, open questions, out-of-scope, and metrics. Leave out detailed visual design, implementation details, and project management.
- The most useful section is often "open questions": what we don't yet know, who will figure it out, by when.
- Update the PRD as decisions evolve. A frozen PRD becomes irrelevant within weeks. A living one stays a useful reference throughout the build.