How to write a task a developer cannot misunderstand

Most projects that go wrong do not go wrong in the code. They go wrong in the first email, when "a simple export to accounting" meant one thing to the person who wrote it and another to the person who read it. Six weeks later both are right, and both are unhappy.

You do not need a forty-page specification to avoid that. You need three short sections, written down, before anyone writes a line of code.

1. What you have now

Describe the starting point, as it is today, not as it should be.

• The systems involved. "An online shop on PHP 7.4, our own code. Accounting in Xero. Stock in a spreadsheet the warehouse updates every evening."
• Who uses them, and how much. "Three people in the office, about 40 orders a day, twice that in December."
• What hurts. "Someone copies every order into Xero by hand. It takes an hour a day and errors are found at the end of the month."

Screenshots help. So do the boring numbers: how many products, how many orders, how old the server is. A developer who knows the server runs PHP 7.4 will not propose something that needs PHP 8.4 without telling you.

2. What it should do

Now describe the result, in terms of what people will see and do, not how it should be built.

When an order is paid in the shop, an invoice with the same lines, prices and VAT appears in Xero within five minutes. If it cannot be created, the office gets an email with the order number and the reason.

That is a good task. Notice what it does not say: nothing about APIs, queues, cron jobs or frameworks. Those are the developer's job. Yours is to be precise about the outcome:

• Name the edge cases you already know. Refunds. Orders paid in two parts. Customers from outside the EU. A product that was deleted after the order.
• Say what is out of scope. "Stock sync is not part of this task." Out of scope is the most useful sentence in any task: it is where most arguments end before they start.
• Say what must not change. "The checkout must look exactly as it does now."

3. How you will check it

This is the section people skip, and the one that matters most. Write down, before the work starts, how you will decide that it is done.

• "We place ten test orders, including one refund and one order from Switzerland. All ten appear in Xero correctly."
• "We switch the Xero connection off for an hour. The office receives one email per failed order, and nothing is lost when it comes back."
• "The person who copies orders today stops doing it for a week and nothing goes wrong."

These are acceptance criteria. They turn "I think it works" into "it works, here is how we know". They also make the price clearer: a developer who can see the finish line can tell you what the road costs.

Four sentences that cause trouble

• "Like Amazon, but simpler." Simpler in which way? Say which parts you mean.
• "It should be fast." How fast, measured where? "The product page loads in under two seconds on a phone" can be checked.
• "The usual features." There are no usual features. List them.
• "We will know it when we see it." You will, but only after paying for the versions you did not like. If you really do not know yet, say so, and start with a small paid discovery instead.

When you cannot write it yourself

Sometimes the honest answer to "what should it do?" is "we are not sure yet". That is fine, and common. Then the first piece of work is the task itself: a short discovery stage that ends with these three sections written down and a price for the rest. It costs a little, and it is the cheapest part of the project to get right.

A template

What we have now
- Systems:
- Users and volumes:
- What hurts:

What it should do
- The result, as people will see it:
- Known edge cases:
- Out of scope:
- Must not change:

How we will check it
- Test 1:
- Test 2:
- Done when:

Copy it, fill it in, and send it to us, or to any developer. You will get a better answer, and a better price, from all of them.

Our request form asks for the first two sections in two questions. Start there.