What a spec is for

A product spec, often called a PRD for product requirements document, exists to create shared understanding. It helps everyone on the team agree on what problem is being solved, why it matters, what success looks like and what is in and out of scope. Code, designs and tests come later and should all trace back to it.

What a spec is not

• Not a contract. The spec will change as the team learns. Treating it as a fixed agreement creates arguments instead of better products.
• Not a design document. It describes needs and constraints, not every pixel. Designers own the design.
• Not a technical design. It says what the system must do, not how to build it. Engineers own the architecture.
• Not a place to hide decisions. If something important is decided, it should be easy to find, not buried on page nine.

Why specs fail

Specs usually fail in one of two ways.

Too vague: "Add team permissions so admins can control access." Engineers are left guessing what roles exist, what each can do and what happens to existing users. They either guess or come back with dozens of questions, which wastes time on both sides.

Too long: twenty pages covering every detail, written before anyone discussed the problem. Nobody reads it fully, so key points are missed, and the document is out of date within a week.

The right length

Match the length to the uncertainty and size of the work:

• A small change, such as a new filter, might need a few paragraphs in a ticket.
• A medium feature, such as a new notification setting, fits on one page.
• A large project, such as team permissions, deserves a full PRD of a few pages with linked designs and diagrams.

A good test: could a new engineer read it in fifteen minutes and explain the problem, the goal and the scope back to you? If not, it is either missing key information or contains too much.

Our example

Throughout the course we will write a spec for adding team permissions to a project management tool. Today every member of a workspace can do everything, including deleting projects. Larger customers have asked for control. It is a classic feature with many edge cases, which makes it ideal for practice.

In the next lesson we look at the sections of a useful PRD and what each one is for.