Writing a spec developers will actually read

What belongs in it and what does not

A spec that describes every pixel becomes a document nobody updates after two weeks. A spec that describes only a vision generates twenty questions a day. The point in between: for each capability — who uses it, what happens on the normal path, what happens when something fails, and the condition under which we agree it is done.

Acceptance criteria are the part that saves most of the arguments. “The user receives a notification within a minute” is a criterion; “the process will be fast” is a wish.

Write flows, not screens

Describe the flow as a sequence: starting state, action, result. Then write the failure paths — no connection, the user closed midway, the file is corrupt, permission denied. In real projects, failure paths are half the work and a quarter of the spec.

Screens get redesigned; flows stay. That is why design is linked from the spec rather than embedded in it.

The part everyone skips

State explicitly what is out of scope for this version. A “not now” list is a management tool, not an apology: it lets you say “right, and that comes next” instead of relitigating in every meeting.

Add the assumptions you are relying on. A written assumption is a managed risk; one that stays in someone's head is a surprise.