PRDs are the thing people complain about most. Either they’re 40 pages long and nobody reads past page two. Or they’re one-line Jira tickets that say “Add profile filtering” and engineering has to reverse-engineer what you actually meant. Or they’re scattered across three documents and a Slack thread and everyone’s working off different versions. Or they don’t exist and you’re explaining the feature in person to each person individually, which means it shifts slightly each time you tell it.
There’s a reason everyone hates them: most PRDs are written to cover the PM’s arse, not to help the team build the right thing.
Here’s what a PRD actually needs to do: It needs to make the implicit explicit. The thing that’s clear in your head needs to be clear on the page so that the person building it is solving the same problem you think they’re solving.
I’ve seen PRDs that are fifty pages of use cases and wireframes and flow diagrams. I’ve also seen PRDs that are literally a screenshot with “make it work on mobile” scrawled on it. The first one looks impressive and probably took twenty hours to write. The second one is useless. The real answer is somewhere in between, but closer to the second than the first.
Here’s the structure I’ve found actually works:
Problem statement. What are we actually trying to solve? Not “users want profile filtering” but “new users abandon during onboarding because they don’t understand if the app is for them.” Be specific. Be brief. This is one or two paragraphs.
Success metrics. How will you know this worked? Not “users use the feature” but “75% of new users complete onboarding” or “time to first completed workout drops from two weeks to one week.” Metrics should be measurable and connected to business outcomes. If you can’t articulate how you’ll know this worked, you probably don’t understand the problem well enough yet.
User stories or use cases. A few concrete scenarios of how someone will actually use this. Not generic (“As a user, I want to filter profiles”) but specific (“Sarah does yoga four times a week, and she wants to find instructors who specialise in yin yoga and hip mobility, so she only has to scroll through classes that are actually relevant to her”). Three or four of these, enough to make the scenario real.
Out of scope. This is the bit that matters and the bit most PRDs skip. What are we not doing? Are we not building social features? Are we not integrating with Spotify? Are we not supporting dark mode in this version? Being explicit about what you’re not doing prevents the feature from expanding mid-build. It’s also a gift to your engineering team because it tells them what not to worry about.
Open questions. What are you genuinely unsure about? Are we unsure whether users want to filter by instructor or just by style? Are we unsure how to handle the case where someone has no preferred instructors? Are we unsure if this should be a modal or inline filters? Put it down. This tells engineering where they can have a conversation with you before they start building.
I learned the power of “out of scope” and “open questions” from watching a disaster in LMS configuration. Someone would write a requirement for “better reporting,” which sounds clear until you realise that reporting means: standard reports, custom reports, real-time dashboards, integrations with BI tools, API access to data, historical data, role-based access to reports, exporting to different formats, and about seventeen other interpretations. Because nobody said what reporting actually meant or what it explicitly didn’t mean, engineering built one version, the stakeholder wanted another, and the whole thing went sideways.
The PRD that would have prevented that mess wouldn’t have been longer. It would just have been clearer: “Out of scope: real-time dashboards, BI integrations, custom reporting. We’re building standard canned reports for completion rates and engagement.” Done. Now everyone knows what we’re doing.
Open questions are where the PM admits uncertainty without seeming incompetent. “Do we surface the time-to-complete metric prominently, or is it secondary information? We should probably test this with a few users before building.” This tells engineering that you might loop back with more information, rather than that you’re wishy-washy or didn’t think it through.
The length should be whatever it needs to be, but probably not more than five pages if you’re doing it right. One page for problem and metrics. One page for user stories. Half a page for out of scope. Half a page for open questions. The rest is context, mockups, or details specific to your situation.
What you should avoid: exhaustive wireframes (the designer will do this, and it changes anyway), step-by-step flows for every edge case (you can’t predict them all anyway), lengthy business justifications that would be better in a separate doc, or anything that’s just rephrasing the same idea seventeen ways.
Write in plain language. “Users struggle to find instructors who teach their preferred style of yoga” is better than “Enable discoverability of instructor offerings through style-based classification mechanisms.” Nobody reads that stuff.
Be opinionated about what matters. If you think the experience needs to be snappy because people are browsing between gym equipment, say that. If you think this should feel fun and encourage exploration, say that. Give the team the reasoning so they can make consistent decisions about details you didn’t predict.
And be honest about what you don’t know. The worst PRDs are written by people who are pretending certainty they don’t have. The best ones are written by people who are clear about what’s decided and what’s still open for conversation.
The real test of a PRD is whether engineering reads it and comes back with the right questions. Not “what’s a profile?” questions, which means you weren’t specific enough. But “should we sort by relevance or alphabetically?” questions, which means they understand the problem and are thinking about the details. Or “we could do this with a filter modal or with faceted search on the listing page, which feels right to you?” which means they’re offering technical options and want input on the strategic direction.
That’s the PRD working. Not because it’s long or pretty or comprehensive, but because it did its actual job: it took what was in your head and made it explicit enough that other smart people could work with it.