How to Write a Specification for a Developer Without a Technical Background: Scenarios, Data and Decisions

A good specification is not a list of screens and not a request to "make it like theirs". It is a set of written scenarios: what starts the process, what data it needs, what decision the system makes, what happens when something is wrong, and what counts as done. It can be written in entirely business language, provided it contains real examples.

What a written scenario looks like

A scenario is one complete story of what happens, from the event that starts it to the result. These are its parts:

• Who. Who runs it - an employee in a specific role, a customer, or the system itself at a set time.
• What triggers it. A click, an incoming document, a time of day, or a status change.
• What must be true first. A precondition, for example that the customer exists and is not flagged as blocked.
• What actually happens. A sequence of actions, in short sentences.
• What gets saved and what gets sent. Which data is written, where, and who is notified.
• What you see at the end. The observable result, for the person running it and for anyone affected.

A scenario that runs past one page is probably two scenarios. Splitting it is specification work, not development work.

The four things every scenario must name

• Data and a source for every field. Not "customer details" but name, phone, customer number, each with where it comes from.
• The decision and the rule behind it. If the system decides something, write the rule out explicitly, including the edge cases.
• The unhappy path. What happens when a value is missing, arrives twice, arrives late, or is rejected.
• A definition of done. A sentence somebody can carry out and answer yes or no to.

The most dangerous field in a specification is not the one that was forgotten but the one written with no source. It looks defined, and in practice somebody will have to decide it mid-build.

A badly written requirement, rewritten

The original requirement: "The system should send a reminder to customers who haven't paid."

That sentence sounds clear and hides at least seven decisions. The table takes it apart:

The rewrite: once a day at a fixed hour, in a fixed timezone and on business days only, the system finds every invoice in status "sent" that is more than seven days past its due date and is not marked paid or credited. Each such invoice gets one message to the address on the invoice. If there is no address, the invoice goes onto an exceptions list that is reviewed each morning. If the message bounces, a note is written on the customer and an alert goes to the process owner. Each invoice receives at most one reminder per week and no more than three in total. Definition of done: every invoice in the list has either a send record or an exception record - no invoice has nothing against it.

The second version is several times longer, and that is the point. Every line in it is a decision that would otherwise have been made without you.

Which decisions are yours and which are the developer's?

This boundary prevents most of the later arguments:

• Yours. Rules with business consequences, wording a customer sees, what is in and out of scope for the first phase, who approves, and what happens in an exceptional case.
• The developer's. How data is stored, in which tools, how the schedule runs, how retries are handled, and how the code is structured.

When a client dictates the right-hand column, the project loses the knowledge of the person building it. When a developer is forced to decide in the left-hand column, a business decision gets made by somebody without the context - and it surfaces only when someone sees an unexpected result.

What does "done" mean, and who says so?

"Done" is a list of checks a person can run themselves and tick off. Not "the system works", but:

1. I entered a valid record and the result appeared where it was specified.
2. I entered a record with a missing field and got the message that was defined.
3. I submitted the same record twice and exactly one result was created.
4. I stopped the system mid-run, and a re-run created no duplicates.
5. I opened the exceptions list and found precisely the cases I broke on purpose.
6. I confirmed that an unauthorised person cannot see the screen.

The person who says so is the process owner - whoever suffers when it fails - not whoever commissioned the project from above.

The unhappy paths people forget most

• The same action was submitted twice because somebody clicked again.
• A run stopped halfway and left half the work done.
• A field that was always populated arrived empty for the first time.
• A record was edited after it had already been processed.
• Two people edited the same record at the same moment.
• A new run started before the previous one finished.
• A clock or timezone change shifted the time window.
• The person who held the credential left the company.

Walking this list against every scenario finds more gaps than any other review at the specification stage.

Related: how to scope a project properly, connecting systems in an Israeli business, when to use an automation tool and when to write code.

Sources

• Cucumber - Gherkin syntax reference
• Cucumber - Writing better Gherkin
• Microsoft - Anti-corruption layer pattern