Writing a specification you can accept against

The situation

A precision engineering firm in Rajkot runs its shop floor from three Excel files. One holds job cards, one tracks which machine is free, and one lists what each customer has been promised. The owner wants a simple web system to replace them. In the first call they say, "It should work like our Excel, but better, and the supervisors should be able to use it on their phones."

That sentence is a good start for a conversation and a poor basis for acceptance. "Better" cannot be tested. "Work like our Excel" depends on which of the three files you mean and which of the many habits around them you want kept. If the build is paid for after acceptance, both sides need something sharper: a document that says, line by line, what the finished system does, so that on the day of review you can sit with it and tick each line or not.

The same method applies whether you write the specification yourself or review one the team drafts for you after discovery.

What a specification is for

A specification has two jobs. Before the build, it tells the team what to make and lets them estimate hours. After the build, it is the test you run. Most specifications are written only for the first job, so they describe intentions ("the system will manage job cards"). A line you can accept against describes an outcome you can observe.

A useful test for every line: could someone who was not in the meetings check it in ten minutes, using only the system and the document? If not, rewrite the line.

Steps

1. Start with the people and the work they do

List the people who will use the system and the tasks each one performs in a normal week. For the Rajkot firm this might be:

• The office manager creates a job card when a purchase order arrives.
• The supervisor assigns a job to a machine and an operator.
• The operator marks a stage complete from a phone.
• The owner checks which jobs are late each morning.

Keep this list short and real. If a task happens once a year, note it, but do not let it shape the first version.

2. Write each requirement as something you can observe

Turn each task into statements that describe what a person sees or can do. Compare these two:

• Weak: "Supervisors can manage machine allocation."
• Better: "A supervisor can assign an open job card to one of the 14 machines in the machine master. A machine already assigned for that shift shows as busy and cannot be selected."

The second version names the user, the action, the data and the rule. It can be tested in a couple of minutes.

3. Give real examples and real data

Attach a sample of your actual data: ten job cards, the machine list, a typical purchase order. Examples settle many arguments before they start. If a job card in your business can have five stages or fifteen, say so and attach one of each. If customer names are in Gujarati in your current sheet, say whether the new system must store and print them that way.

Where the data includes personal details of customers or staff, mention it here, because it affects how the system stores and shows that data.

4. Write down the rules nobody mentions

Every business has rules that live in people's heads. A job cannot go to dispatch until quality has signed it off. Rush orders from two named customers jump the queue. Prices must be hidden from operators. These are the lines that cause disputes at acceptance, because the team could not have known them. Ask each user, "What do you check before you do this?" and write down the answers.

5. Say what is out of scope

A short "not in this version" list protects both sides. For the Rajkot system it might say: no Tally integration in phase one, no customer login, no offline mode for the phone screens. Anything on this list can become a later phase, estimated separately.

6. Set the non functional basics

Some requirements describe how the system behaves: on which devices, for how many people, and with which permissions. Keep these few and specific:

• Which browsers and phones it must work on, for example Chrome on the Android phones the supervisors already own.
• How many people will use it at the same time.
• Who can see and change what (roles and permissions).
• Which reports must export, and to what (Excel, PDF).
• Where it will be hosted, and who arranges and pays for hosting, agreed in writing before work starts.

Avoid vague targets such as "fast" or "secure". If speed matters, give a number you can check, such as "the day's job list loads within three seconds on the office connection".

7. Define how acceptance will run

The specification should say how testing will happen: who tests, on which environment, with what data, and how issues are logged. It should also state the length of the review window and what follows once you accept. Read those lines closely before you sign.

8. Split it into increments

Work is built and reviewed in increments, so group the requirements into chunks you can review on their own. For the job card system that could be: masters and job card creation first, machine assignment second, operator updates on the phone third, reports last. Each increment gets its own short acceptance list drawn from the main document.

What a specification cannot do

A specification cannot predict everything. You will discover things during the build that you did not know you needed, usually once you see the first screens. That is normal. When it happens, the change is written down, estimated and agreed before it is built. Slipping it in quietly feels friendly at the time and causes trouble later, because nobody can then say what was agreed.

A specification also cannot replace your time. If the people who will use the system do not take part in writing and testing it, the document will describe what the owner imagines, and the shop floor may work quite differently. Budget a few hours of each key user's time for review.

Finally, a long document is rarely a better one. Forty clear, testable lines beat two hundred vague ones. If you find yourself writing paragraphs, you are probably describing a wish. Turn it into a line someone can test.

A short checklist

Before you sign a specification, check that:

• Every user role and its main tasks are listed.
• Each requirement names who does what, with which data, under which rule.
• Sample data and documents are attached.
• Unwritten business rules have been asked about and recorded.
• There is an out of scope list.
• Devices, browsers, roles and exports are stated.
• The acceptance process, review window and payment timing are set out in the document or agreement.
• Requirements are grouped into increments you can review one at a time.
• Someone who was not in the meetings could test each line.

To see where the signed specification sits in the whole process, read how pay after acceptance works from first call to invoice.