Technical specification translates expectations into verifiable results
The terms of reference describe what needs to be done and what signs indicate that the work is ready. For a small digital task, clarity of requirements is more important than the length of the document.
An illustrative project needs a consultation enquiry form. “Make a convenient form” sounds clear until the first test. Which data should it collect? What should appear on error? Where should the enquiry go? How will someone know submission succeeded? If answers emerge only after development, some work will need to be redone.
The example below concerns a small web task. Procurement, construction and regulated industries have their own documentation requirements. This example demonstrates how to express testable conditions, rather than prescribing a universal mandatory specification format.
- Request
“The form should be convenient and modern.” This cannot be tested unambiguously.
- Requirement
“After a successful submission, a person sees a confirmation; clicking again does not create a second request.” There is observable behavior.
Example enquiry form requirements
| Area | What to describe |
|---|---|
| Entry point | Where the visitor opens the form and what action they want to take |
| Data | What fields are needed and why; which are required |
| Success | How submission is confirmed and where the enquiry arrives |
| Error | What happens if the field is invalid and there is a temporary failure? |
| Devices | What sizes and input methods need to be checked |
| Boundaries | What related functions are not included in this job? |
| Acceptance | Who tests the scenarios and where they record feedback |
Do not add fields “just in case”. Each field needs a clear purpose and appropriate data handling. If the team does not know why it needs a middle name, that is a requirements question rather than a designer’s task to fit in another input.
Separately attach an example of the content and conditions if they have already been agreed upon. The link to the mockup is useful, but it's not a substitute for describing the behavior: a static picture doesn't explain what happens when the send fails.
How to write acceptance criteria
The criterion should allow you to see the result. Instead of “works quickly,” agree on specific verification conditions if speed is really important. Instead of “handles errors gracefully,” list the significant situations. There is no need to make up exact numbers without a basis: first find out what the user and the system require.
- Condition
The visitor has filled in the required fields with valid data.
- Action
Clicked the submit button once.
- Observation
Receives clear confirmation; the enquiry appears in the agreed location.
Define a separate error scenario: a required field is empty, someone tries to submit the form, the interface explains what to correct and does not lose existing input without reason. A network failure needs its own scenario. These distinctions prevent one successful click from being treated as a complete test.
How to negotiate changes
Technical specifications do not make the project immovable. As you work, new restrictions or useful information may appear. It is important to maintain a distinction between correcting non-compliance with an agreed requirement and new scope. Both cases require attention, but have different impacts on agreements.
- Describe what requirement is changing and why.
- Check the impact on work already done and adjacent scenarios.
- Agree on the new scope and timing with those affected by the change.
- Update the current version and acceptance criteria.
- Tell the contractor which version to check the result against.
Avoid several “final” documents with no clear indication of which is current. Keep one working version and a short history of important decisions. A small team needs a simple process; bureaucracy should not cost more than the change itself.
Completed example of enquiry form requirements
For an illustrative course page, agree on a minimal scenario: visitors leave a name and email address to receive an answer about the programme. The name is for addressing them and the email for replying. Do not add other data “just in case”. Consent wording, grounds for processing and retention periods are determined separately by those responsible; a generic form example does not resolve them automatically.
Requirement F-01: visitors can complete the form using a keyboard; every field has a visible label. F-02: an empty required field displays a clear message beside it, while entered values remain on screen. F-03: after successful submission, users see confirmation and understand what happens next. Do not show success before the system confirms that the enquiry was accepted.
- Field error
The reason is clear; other values are retained.
- Network failure
No false success message; retry is available.
- Success
The enquiry is accepted; the visitor understands the next step.
Requirement F-04: after a network error, the form says submission was not confirmed and allows retrying without re-entering data. F-05: pressing again during submission must not create several enquiries. Disabling the button alone is insufficient protection against duplicates: handling repeated submissions must be agreed and tested on the receiving side too. The developer chooses the specific mechanism.
Requirement F-06: the enquiry reaches the agreed processing location and the person responsible understands its source. The illustrative specification uses an enquiry queue, but the team identifies the actual system and access before development. “Send it somewhere by email” is not a complete specification. Describe separately who checks delivery and how failures are detected.
Test requirements through scenarios rather than an impression that it seems to work
Record an observable test for every requirement. With the email field empty, submission does not occur, the reason appears beside the field and the name remains. With the server unavailable, no false success message appears. After a successful response, the enquiry is found in the agreed queue and the visitor receives clear confirmation. The tester must know which inputs to use and where to look for the output.
Choose specific supported devices and browsers based on the project’s audience. “Perfect on every device” is not testable. For mobile scenarios, check more than width: the open keyboard must not hide the needed button, labels must be readable and errors must not require horizontal scrolling. Test keyboard access separately from mouse clicks.
Link the acceptance note to the requirement: “F-04: after a network error, the name is cleared.” This allows you to distinguish a defect from a new request, for example, adding a phone number. The new field changes the data, validation and processing; it is assessed as a change, even if visually it is small.
Before development, check unresolved points: enquiry recipient, integration, state designs, person responsible for copy and test data. If these are undefined, flag them as blocking questions and assign owners. A detailed specification cannot compensate for a missing decision.
Choose the next specification check
Start with one task: “Clarify enquiry form states before development.” Record the expected outcome in the description: agreement on successful submission, field errors, temporary failures and how the outcome is confirmed. You do not need to move the entire article into the service; save what you will need while doing the work.
Schedule this work before implementing the form. After agreement, create a separate task to test the scenarios so acceptance stays in the plan.
- Create a task with a specific action in its title.
- Add the completion conditions and necessary context to the description.
- Choose a day and check whether the work fits alongside your other commitments.
Signing up for Sinqly is free. You can also work through the article's example in an ordinary document; the app helps you return to the actions you chose.
Check the specification before handover
Ask the person doing the work to explain the task in their own words and identify where they would need to guess. This is a search for gaps in the document, not an attention test. If two people interpret a condition differently, add an example or clarify the term.
Then walk through the whole user journey: entry, action, success, error and returning to work. Check whether a short phrase hides a separate feature. “Also send a notification” may require recipients, conditions, content and handling repeated attempts and failures.
A good technical specification facilitates both implementation and acceptance. After it, fewer decisions have to be made by chance on the last day.
More questions to clarify
Is it necessary to describe the technical implementation?
If there are real restrictions - yes. But you shouldn't dictate internal design without reason when only testable behavior is important.
Is it possible to use a mockup instead of technical specifications?
A mockup shows appearance. Behaviour, errors, data and acceptance usually need explanations. For a small task, keep these together.
Who is responsible for the readiness criteria?
The people defining requirements, doing the work and accepting the result agree on the criteria. The person doing the work should not have to guess the approver’s expectations.
Was this helpful?
Rate the article and tell us what was missing. Your feedback goes to the Sinqly team and will not be published on the site.
Sources and notes
- Atlassian: product requirements template
- W3C WAI: Notifications and Feedback in Forms
- The suggested process reflects editorial practice; it does not promise identical results for everyone.
Task acceptance criteria: how to write and check them, with examples
Observable conditions instead of “do it well”: acceptance criteria for a form, success and failure scenarios, task boundaries and a disputed result worked through.
User stories: how to write one, with examples
The user story format, three improved examples and a workshop booking story: distinguish a need from a feature, add acceptance criteria and split work that is too large.
Monthly content plan: example and practical template
Build a realistic content plan: goal, recurring topics, a sample month and the path from idea to publication. Account for preparation, approval and rescheduling.