Functional Spec

Deciding what to build and why doesn't start the building. Dozens of decisions still sit in between. For an invite feature: how many days before the invite email expires, what someone sees when they click an expired link, what happens when an address that was already invited is entered again. None of them is large, and none of them settles itself.

When those decisions aren't in a document, they surface one at a time while the work is underway. Theo asks four times a day, Mia answers each time, and the answers live in a chat thread. Two weeks later at review, "clicking an expired link gives you a blank page" isn't a build mistake — it's something nobody ever decided, and fixing it means another round of deciding and building.

Leaning on mockups instead of a document stalls at the same place. A mockup usually shows one screen on a good day, so the empty list and the unreachable server aren't in it.

A functional spec collects those decisions in one place right before the work starts. Pair conditions with outcomes in writing and the questions that would come up during the build come up while the document is being written instead. The total number of questions doesn't drop; it moves to a cheaper moment.

The document has five slots. The order carries meaning: what the document covers comes first, the elements and behaviors follow, and the standard for calling it done comes last.

1. Subject and boundary — the first line fixes which screens and which feature this document covers. Writing up an invite feature without settling whether the invitee's signup flow is included leaves every reader imagining a job of a different size.
2. Element list — every single thing placed on the screen. Not only buttons and input fields but helper text, the view shown when nobody has been invited yet, and the indicator shown while the list loads.
3. Behavior and conditions — what happens on each action, paired with the condition it happens under. "Pressing send dispatches the invite" is half a line; the slot fills once no role is selected, the address is already invited, and the limit is exceeded each get an outcome.
4. Exceptions and errors — everything that isn't the happy path. What to show when the network drops, when the same button is pressed twice, and when someone without permission opens the URL directly. Most of the questions that come back from the team come from this slot.
5. Acceptance criteria — the conditions under which the feature counts as finished. Written as checkable sentences, so a reviewer can walk the list.

Where prose gets hard to follow, a picture goes next to it. Several screens with many branch points call for a flow chart; one object moving between many states calls for a state diagram. If a single invite moves between sent, accepted, declined, expired, and canceled, one drawing beats ten sentences.

A rule that reaches past this screen into the whole product goes into a product policy instead. Which account tier may send invites is a rule that touches every document and every plan, and writing the same rule in two places guarantees a day when only one of them gets updated.

The writer is usually the product manager who owns the feature, with a designer filling it in alongside when the screen carries many states. A common order is to sketch a wireframe — structure and layout with none of the styling — and fill in the document while looking at it.

Three kinds of readers, each on a different slot.

1. Engineers — read behavior, conditions, exceptions, and errors, then answer how long it takes. The number of cases is the estimate, so with those two slots empty there's nothing to estimate from.
2. Designers — count the element list to find how many states they owe. Six elements plus empty and error states pushes the count past ten screens.
3. Quality assurance (QA) — copy the acceptance criteria and exception slot straight into a test list, so an unwritten case goes unchecked.

Writing it isn't a one-time job. Decisions that change during the build and never return to the document leave it stale within two weeks, and a stale document is worse than none. Without one, people at least ask; with a stale one, nobody doubts it and they build exactly what it says.

"The functional spec isn't out yet, right? I can't estimate without knowing how many states there are."

The number of cases isn't settled, so no date can be given.

"That wasn't in the spec. Adding it means revisiting the schedule."

The request falls outside the agreed boundary, so the timeline conversation reopens.

"I updated the spec but never shared it. Sending the current version now."

Fixing a gap between the document and the decisions that were actually made.

The week Pagedeck rebuilt its invite feature, Mia circulated a draft spec. Noa went through the element list first and named three missing screens: nobody invited yet, the invite limit used up, and the list still loading. None of the three existed in the mockups.

Theo looked at the exception slot and found that accepting an expired invite had no outcome written for it. When Mia drew the state diagram, there was no arrow at all from expired to accepted, and a screen blocking that path was added on the spot. The document took two days, and those two days absorbed five or six questions that would otherwise have surfaced at review.

The most common mistake is treating the spec as something written once before development and then finished. It exists to settle things before building, so finishing it looks like the end of its job. But decisions keep changing during the build. If raising the invite limit from twenty to fifty never reaches the document, the person reviewing the work two months later judges it against twenty.

The second mistake is assuming mockups make a spec unnecessary. Every screen is drawn, so there seems to be nothing left to write. A drawing shows one moment; a spec records the conditions between one moment and the next. The rule that the send button stops working past the limit doesn't live in a picture, so building from mockups alone leaves that rule to whoever writes the code, and it surfaces at review.