A useful specification makes disagreement visible
“Let people book a workshop” sounds clear until the last place is taken. The useful part of a specification starts there.
A booking page has one place left. Two people try to reserve it. The sentence “Visitors can book a workshop” has nothing to say about what happens next.
That sentence may be enough to start a conversation. It’s a poor place to end one. A project specification becomes useful when it finds the decisions concealed inside apparently simple requests, while there’s still time to argue about them in a document.
This applies beyond software. An exhibition brief, a commissioned report or a building survey can all sound agreed until somebody tries to produce the result. A good specification gives that person enough information to notice where their understanding differs from yours.
Follow one person through the awkward case
Suppose a small arts centre wants online reservations for free workshops. The organiser imagines a form that sends an email. The designer imagines a calendar. The developer imagines live availability. Everyone can approve “a simple booking system” and leave with a different project.
Rather than listing more adjectives, describe a visitor’s attempt to get the last place:
A visitor chooses a workshop with one place available and submits their name and email address. A place is confirmed only after the booking is accepted. If somebody else has taken it, the visitor sees that the workshop is full and is offered the waiting list. We must not send both visitors a confirmation for the same place.
That example raises useful questions. Is there a waiting list? Does the visitor have to consent to joining it? Can staff change capacity? What happens if the confirmation email fails after a reservation succeeds?
You don’t have to answer every question immediately. Write unresolved choices as questions, with someone responsible for resolving them. Calling an assumption a requirement merely postpones the disagreement until it costs more to fix.
State the result, then explain the constraint
“Use a calendar” prescribes an interface. “Visitors must be able to find a workshop on a day they are free” describes something the interface must help them do. A calendar may be the right answer; a short list might be better when there are only four events.
Some constraints really are fixed. Perhaps staff already maintain workshop dates in an existing system, or the centre cannot take online payments this year. Put those facts in the specification and explain their effect. Otherwise a collaborator may spend a week solving a problem the organisation has already ruled out.
The document can be short. A paragraph about the intended result, two or three worked situations, the firm constraints and the open questions may cover a modest project. Use headings that reveal those subjects, rather than a template with fourteen empty sections.
For the arts centre, one explicit exclusion matters: this release reserves free places; it doesn’t sell tickets. That boundary prevents an apparently small request for card payments from slipping into an agreed piece of work. It also tells the centre what it will still have to handle elsewhere.
Give the reviewer something to try
“Easy to use” is an intention, not a useful completion check. “Staff can cancel a reservation and make the place available again” gives a reviewer an action and an observable result. If a cancellation must also notify the visitor, say so. Test the complete situation you care about, including the consequences.
A small checklist can track those checks, but a tick doesn’t preserve the evidence by itself. Add the date and outcome of a review where that matters. If the project is larger, link to the test record instead of stuffing every result into the specification.
When an agreed choice changes, retain the earlier version and record why. A version comparison can show that the waiting list disappeared; it can’t explain that the centre had nobody available to manage it.
The next useful edit to your specification may be a single example. Find the sentence everyone has nodded at, put a person in an awkward situation, and see whether the document can tell you what should happen.
Find app controls and examples in the Clarity documentation
A little more room to think.
A free, local Markdown hub for Mac.
Mac app details