Writing requirements an engineer can actually build from

You know your business better than any developer ever will. You know that Friday deliveries are different, that one supplier invoices in a currency nobody else uses, that the intern must never see payroll. The whole game of requirements is moving that knowledge out of your head and into a form an engineer can build from without guessing, because everything an engineer guesses, you eventually pay to have re-guessed. Writing requirements is a skill, it is learnable, and this article is the short course we wish every client had read before their first project. Some of ours have, and those projects went noticeably better.

Write what happens, and who it happens to

Weak requirements describe qualities. Strong requirements describe events. "The system should be user-friendly" gives an engineer nothing to build and gives you nothing to check. Compare: "A dispatcher creates a delivery in under a minute using only the keyboard, and an error in the address is flagged before saving, in plain words, next to the field it concerns." Same intention, but now it can be built, tested, and argued about precisely, which is the entire job of the document. The pattern is always the same: who does what, when, and what must be true afterwards.

Examples beat definitions

When a rule is fuzzy in your head, do not define it. Tell it as a story with real numbers. "A driver clocks in at 06:00, drives until 10:30, rests 45 minutes, and drives again until 15:00. Is that a violation?" One concrete example like that is worth a page of adjectives, and three examples, including one ugly edge case, will surface more truth than a workshop. Engineers convert examples into rules for a living. What they cannot convert is vibes (or they can poorly, in the age of vibe-coding).

The edge cases are where the money is

The happy path is easy to describe and nearly free to build. Budgets die in the edges, so drag them into the light early. What happens when the payment fails halfway? When two people edit the same record at once? When the GPS box in a vehicle goes silent for an hour? Write down every "but sometimes" your team can remember, because each one you name during planning costs a sentence, and each one you discover in production costs an incident, an apology, and a patch. Your staff on the ground know these cases best. Ask the person who answers the angry phone calls, and write while they talk.

Say what it must never do

Some of the most valuable requirements are prohibitions, and clients almost never think to write them down because they feel obvious from inside the business. The intern must never see payroll. A deleted client must never disappear from historical reports. An alert must never fire twice for the same event. Obvious-to-you is precisely the category of knowledge that dies in translation, so give the never-list its own page. It will be short, and every line on it will matter more than an average feature.

You do not have to arrive with this finished

Here's the honest picture: nobody shows up with a perfect document, and we have never expected one. In our own discovery process, Alexandru builds this with you, question by question, and every session ends with "so to confirm:" and the list read back out loud, because a requirement you have not heard read back is a rumor. But clients who arrive having tried, even one rough page of who-does-what and a handful of "but sometimes" stories, save real time and real money, and their projects start with arguments about substance instead of vocabulary.

The software requirements document template we use →

Discovery: we write this document with you →