Skip to content
All articles
Career lessons

Writing requirements people actually read

Most requirement documents are written to be approved, not to be read. A few habits that changed that for my teams.

A document with one highlighted section under a magnifying glass

Most requirement documents are written to be approved, not to be read. They're long, defensive, and full of sections nobody opens after sign-off.

Start with the decision

The first paragraph should say what we're deciding and why now. If someone reads only that paragraph, they should know whether the rest concerns them.

Write the edge cases as questions

"What happens when the user has two active contracts?" invites engineering into the thinking. A rule written as a fact invites them to implement it, even when it's wrong.