Specification

What to build and why goes in the product requirements document (PRD). For a coupon feature, that document carries why this is happening now, how far it goes this time, and what counts as finished. Up to there it serves every reader equally well.

Sit down with that document and actually try to build, though, and a different kind of question starts arriving. Is the confirm button clickable while the coupon field is empty? When the code is wrong, what message appears under the field, and does it disappear after a few seconds or stay? Do an already-used code and an expired code share the same message or get different ones? Each question is small on its own, and not one line of code gets written until they are answered.

Pagedeck had exactly that day while building document sharing invitations. Theo walked over to Mia three times in the morning and four times in the afternoon. What happens when you invite someone who is already invited, whether a sent invitation can be cancelled, and what becomes of the link in the recipient's mailbox after a cancellation came up one after another. Mia answered on the spot and the answers were mostly sensible, but none of those seven decisions were written anywhere. Noa was designing the screens without knowing there was a cancelled state at all, and two weeks later the review made it obvious that two people had built two different things.

Asking isn't the problem. The problem is the questions nobody asks. Ask seven out of ten and quietly decide the other three on your own, and the fact that those three disagree only surfaces on the day the code and the design get put together. Fixing it then costs several times what settling it in advance would have. Thirty minutes of a meeting beforehand becomes days of redrawing screens, rewriting code, and running the review again.

A specification is the proposal to pull all those questions out at once and write down the answers before building. The unit of writing is what separates it from a PRD. Where a PRD draws the boundary of the work, this fills the inside of that boundary with screens and conditions. The goal is not a perfect document but fewer trips back to ask, and if two people built the same thing without one of those trips, the document did its job.

The terms grouped here form a single branch of four kinds. They are not four separate documents so much as one feature written from four angles. What it does belongs to the functional spec, where it sits on a screen to the screen definition, how the path branches to the flow chart, and what moves from which state to which to the state diagram.

1. Functional spec — writes out, in sentences, how one feature behaves under which conditions. "Seven days after the invitation mail is sent, the link expires, and clicking an expired link leads to a screen offering to request a new one" pairs a condition with a result. It takes up the most room of the four, and the other three are ways of reflecting the same sentences back from a different angle.
2. Screen definition — stands each screen up one at a time and records the elements on it and what each element does. For the invitation screen that means an email field, a permission selector, a send button, and a list of people already invited, with an empty state, a typing state, and an error state attached to each. A design file usually shows one healthy state, so every other state gets filled in here.
3. Flow chart — draws the order a user moves through and the points where the path splits. Someone who clicks an invitation link and already has an account goes straight to the document; someone who doesn't goes to signup first. Conditions that pile up into unreadable prose become one glance as a picture.
4. State diagram — draws the states one thing can be in and the routes between them. A single invitation can be sent, accepted, declined, expired, or cancelled, and arrows connect which state can reach which. The missing arrows are the transitions to block, so a question like what happens when you accept an expired invitation falls out of the drawing on its own.

You don't need all four. What decides it is where this particular feature gets complicated. Simple screens with many conditions need only the functional spec; several screens in sequence call for a flow chart; one object moving among several states earns a state diagram. When drawing all four takes longer than building the thing, the document has already overshot. For something like invitations with five states, a functional spec and a state diagram usually cover it.

Whichever kind you write, the fields to fill are much the same. There are five, and leaving one blank sends its reader back to ask.

1. Subject and scope — pin down at the top which screens and which behavior this document covers. Writing about invitations, say in the first line whether the signup flow for the invited person is included or not.
2. Element list — count everything that sits on the screen. Not only buttons and fields but guidance text, the empty state, and whatever shows while data is loading.
3. Behavior and conditions — pair every action with the condition it happens under. "Pressing send issues the invitation" is half a line; the field is full once it also covers no permission selected, an address already invited, and the seat limit reached.
4. Exceptions and errors — collect everything off the happy path. What to show when the network drops, when the same button is pressed twice, and when someone without permission opens the address directly. Most of the questions that come back in practice come from this field.
5. Acceptance criteria — the conditions under which this feature is accepted as finished. They have to be written as checkable sentences, because whoever reviews the work walks this list item by item.

When a rule reaches past one screen and applies to the whole product, that part moves out into a product policy. Who is allowed to invite people isn't a question about the invitation screen; it applies to every document and every plan, so it lives in the policy and this document links to it. Write the same rule in two places and a day comes when only one of them gets updated.

Who writes and who reads is settled too. The writer is usually the product manager who owns the feature, with the designer filling in alongside when a screen carries many states. Readers split three ways and each opens a different field. Engineers read behavior, conditions, exceptions, and errors, and answer how long it will take. Designers read the element list and count the states they have to draw; a common order is to sketch a wireframe first and fill this document in while looking at it. Whoever handles quality assurance (QA) copies the acceptance criteria and the exception field straight into a review checklist. So a blank field stops only the person who reads it. With exceptions missing, development rolls on while the review has no basis to rule on anything. Writing is not a one-time act either. Decisions that shift during the build have to come back into the document, or it goes stale within two weeks, and a stale specification is worse than none at all, because people build straight from it without suspecting anything is off.

Some specifications are written for machines. OpenAPI is the one used for the openings programs use to talk to each other. Written in a fixed format instead of prose, tools read the file and generate documentation pages and validation code from it. The purpose matches the human kind; only the reader differs.

"The spec doesn't cover that case, so I've blocked it for now. An empty value breaks everything downstream."

A report that an engineer made a temporary call because the document had no answer, and a request to confirm it.

"I build against this screen definition, right? Is last week's change in there?"

Asking whether the document is current. Building from a stale one can burn two full weeks.

"Draw the state diagram first. Nothing says where a cancelled invitation goes back to."

Conditions written as prose hide the missing routes, so let's check them as a picture.

Pagedeck's invitation feature runs in a different order now. Mia posts a draft of the functional spec and the screen definition first, and Noa fills in the states per screen while flagging the blanks in comments. What to show when the invitation list has zero entries was the first comment. Theo read the exception field and asked again what happens when the same address is invited twice — and this time the answer landed in the document.

There's also a point at which the document closes. Mia takes comments through Wednesday, finalizes on Thursday, and work starts after that. Changes arriving later go through editing the document and dating the edited line. The procedure looks fussy, but it is the step that keeps a verbally agreed change from turning into an argument at review time.

The most common mistake is assuming a design file makes this document unnecessary. The design looks far more concrete and shows the screen itself, so the thought is natural. But what a design file holds is the visible states, and usually a single scene where everything went well. The screens for an empty invitation list, a mistyped address, or an exceeded seat limit are often not in the file at all, and even when they are, the picture doesn't say when the app moves to them. Build from the design alone and engineers settle those conditions individually, and review day reveals two different products. The two aren't competing documents; they fill each other's blanks. The design owns how it looks, and this document owns when it looks that way.

The second is believing more detail always makes a better document. It exists to cut down on questions, so writing more feels safer. But nobody reads thirty pages to the end. Record the button padding in pixels and the exception that actually matters gets buried between those lines, and the smallest design change makes the document stale, after which people stop trusting it. The line worth drawing is whether someone will ask about the item again later. Padding is answered by the design file; what happens when you accept an expired invitation is answered here.