Use when drafting, rewriting, or reviewing a product definition or product design document — the artifact that states what a product is, what problem it solves, who it is for, and its core concepts and information structure. Applies when the user asks for a product definition, product design doc, or "PRD-lite", or pushes back that a draft reads like a technical proposal, RFC, or data-model spec. Enforces user-perspective wording, information-structure over schemas, problem-before-solution ordering, and mental-model-first concept writing.
Use when drafting, rewriting, or reviewing a product definition or product design document — the artifact that states what a product is, what problem it solves, who it is for, and its core concepts and information structure. Applies when the user asks for a product definition, product design doc, or "PRD-lite", or pushes back that a draft reads like a technical proposal, RFC, or data-model spec. Enforces user-perspective wording, information-structure over schemas, problem-before-solution ordering, and mental-model-first concept writing.
Writing Product Docs
What a product doc is (and is not)
A product doc answers four questions and nothing more:
What is it — one paragraph a reader can repeat to someone else.
What problem does it solve — the pain, and today's inadequate workaround.
Who is it for — user profiles concrete enough to test membership.
Core concepts & information structure — the concepts, and what the user sees.
It is NOT a technical proposal, RFC, or design spec. When a draft starts carrying
the things below, it has drifted out of "product" and into "engineering" — cut them:
Belongs in a design doc / RFC, NOT a product doc
Data models / schemas (id, createdAt, foreign keys, field types)
Technical constraints (storage layout, model selection, library/engine choice)
Phase plans / milestones / testing strategy
"Alternatives considered" trade-off analysis
Error-handling matrices, boundary-case tables framed for implementers
If the user says "this reads like a technical/proposal doc," the fix is almost
always deleting one of these sections — not rewording it.
The five sections
Order matters. Lead with the problem so the reader feels the need before the
solution is named. Keep the tail light.
1. Problem — the pain + today's workaround, ideally a table
2. User profiles — primary profile + "to-be-validated" secondaries
3. User stories — concrete narratives; end with the shared pattern they reveal
4. Core concepts — each concept: definition + mental model + behavior
5. Information structure — what the user SEES per view + concept relationships
A one-paragraph product definition sits above section 1 (unnumbered intro).
Optional closing sections (non-goals, interface compatibility, future directions)
stay short — one bullet each, no elaboration.
Anti-pattern: opening with "What it is" fully explained, then justifying why
it's needed. Readers can't judge a solution to a need they don't yet feel. Problem first.
User perspective over developer perspective
The single most common defect. The doc describes what the user experiences, in the
user's words — never the system's internals or the developer's vocabulary.
Wording: use what the user would say, not what the code calls it
Engineering names leak into product docs because the writer is close to the
implementation. Translate them back to the concept the user actually perceives.
Common categories of leak:
Leak category
Typical engineering terms
Fix
Data-layer nouns
source, record, entity, artifact, blob, node
Name the thing as the user thinks of it (the file they added, the content they got)
Pipeline verbs
ingest, index, parse, embed, sync, hydrate
Describe the visible process/state, not the mechanism ("processing…" → "ready")
Invisible internals
vector, chunk, token, cache, hash
Omit entirely — if the user never sees it, it isn't product
Infra choices
local vs cloud, service X vs Y, endpoint
Mention only the choice the user actually makes, in their terms
Generic tech placeholders
object, item, resource, handler, config
Replace with the concrete domain concept
The specific mapping is domain-specific; the rule is universal: if the user
never sees or says the word, it does not belong in a product doc. Test each noun
and verb with "would a non-technical user of this product use this word?" If no,
translate it.
Tone: considered, not casual
Product docs read as deliberate, not chatty. Casual or vague phrasing signals the
idea isn't fully formed. Categories to watch, with the direction of the fix:
Undignified pattern
Direction of fix
Colloquial place/action names ("the spot where you do stuff", "the doing area")
Name it by its function or role ("the workspace", "the authoring surface")
Hand-wavy ease claims ("just click and you're done", "super easy")
State the concrete action ("complete in one step")
Filler and hedging ("basically", "kind of", "for the most part")
The underlying rule: every phrase should be one a serious spec would carry.
Information structure = what the user sees, not data fields
The information-structure section describes each screen or view in terms of what
appears to the user: titles, icons, status labels, counts, lists, buttons, empty
states. It never lists database fields. Describe the row the user reads, not the
record the system stores. A visible list of attributes the user perceives is
product; a struct definition with types and keys is a schema — move it out.
Concepts: mental model first
Each core concept gets, in this order:
Definition — one or two plain sentences.
Mental model — the analogy the user holds in their head. This is the most
valuable and most-skipped line: a physical or familiar metaphor ("a desk",
"a folder", "a timeline", "a shopping cart", "a knowledge pack").
Behavior — what the user can do with it, in user-visible steps.
A concept without a mental-model line is under-specified. If you can't name the
analogy, the concept probably isn't crisp yet — surface that to the user rather
than papering over it.
Optionally state a short list of design invariants — the rules that must hold
no matter how the product evolves. These are the durable core; distinguish them
from mutable UI decisions.
Diagrams and notation
Prefer Mermaid for concept relationships so it renders in common hosts
(GitHub/GitLab) without external tooling.
Rendering gotcha:erDiagram with non-Latin (e.g. CJK) entity names fails
to parse on GitHub (ONLY_ONE / cardinality errors). For non-Latin labels use
graph TD with plain nodes and labeled edges instead. Verify any diagram
actually renders before shipping.
ASCII box layouts are fine for screen mockups (sidebar / main-area sketches) —
they convey user-facing structure, not implementation.
Review checklist
Before delivering, verify:
Opens with the problem, not the "what is it" explanation.
Every term is one a real user would say (no data-layer nouns, pipeline verbs, or invisible internals).
The information-structure section lists what the user sees, not data fields.
Each concept has an explicit mental-model line.
No schema, no phase plan, no test strategy, no tech-constraint section.
Tone is considered, not casual — no filler, hype, or hand-wavy claims.
