A useful web-application specification gives the business and the supplier a shared description of what is being built, why it matters and how completion will be judged. It should reduce avoidable interpretation without pretending that every design and technical decision can be settled before discovery begins.
The document is not simply a list of screens, and it does not need to prescribe a programming language or database unless a genuine constraint requires it. Its core subjects are users, processes, data, rules, integrations, quality expectations, ownership and acceptance.
What a good specification should achieve
- Allow different suppliers to understand broadly the same scope.
- Expose assumptions, dependencies and unresolved decisions before they become expensive changes.
- Give designers and developers enough business context to make sensible implementation decisions.
- Provide testable acceptance criteria rather than relying on subjective approval.
- Define what is excluded as clearly as what is included.
- Protect the business's access to data, accounts, documentation and other project assets.
A specification cannot remove every uncertainty. Its job is to make uncertainty visible and allocate a sensible way to resolve it.
The core sections of a web-app specification
1. Business context and intended outcome
Begin with the problem, not the proposed interface. Explain what is happening today, why it is inadequate and what measurable improvement the project is expected to create.
Useful context may include:
- the current process and tools;
- the people affected;
- the cost or risk of the present approach;
- the desired operational outcome;
- constraints such as deadlines, existing contracts or systems that must remain;
- how success will be measured after launch.
“Build a customer portal” is a solution label. “Reduce the time spent emailing documents and give customers a reliable view of request status” is a business objective that can guide decisions.
2. Scope and boundaries
State which processes, user groups, locations and integrations are included in the first release. Record exclusions and future ideas separately so they do not quietly become assumed commitments.
| Include in the scope | Record separately |
|---|---|
| Processes the release must support | Ideas that may be considered later |
| User groups included at launch | Countries, teams or customer types outside the first release |
| Data that will be migrated | Historic data that will remain in an archive |
| Named integrations and responsibilities | Possible future providers or optional connections |
| Required reports and exports | Exploratory analytics without agreed measures |
Boundaries are particularly important when a supplier quotes a fixed price. An apparently small phrase such as “integrate with the CRM” can conceal several systems, data-cleaning work and failure-handling requirements.
3. Users, organisations and roles
List the people and organisations that interact with the system. Describe what each role is responsible for and which records it may view, create, change, approve, export or delete.
Avoid relying only on job titles. Two employees with the same title may have different responsibilities, while several job titles may need the same permission set. Include temporary users, contractors, support staff, system administrators and external organisations where applicable.
For high-impact actions, record whether a second approval, reason or audit entry is required.
4. Workflows, rules and exceptions
Describe each important process from its trigger to its outcome. For every stage, identify:
- who is responsible;
- what data is required;
- which rules determine the next step;
- what notification or deadline applies;
- what happens when information is missing or invalid;
- which decisions can be reversed or overridden;
- how the process ends and how completion is recorded.
The exception paths often determine more of the build effort than the normal path. A specification that says only “user submits, manager approves” is incomplete if submissions can be returned, reassigned, cancelled, duplicated or approved after a deadline.
5. Data and document requirements
Define the main records the system will hold and the relationships between them. For each important field, consider its source, format, validation, ownership, sensitivity and retention needs.
Questions to answer include:
- Which system is authoritative for each type of data?
- Which values are entered, calculated or imported?
- What must be unique?
- Which changes need a history?
- What must be searchable, reportable or exportable?
- Which documents need versions, approvals or expiry dates?
- What data must be migrated, cleansed or archived?
Do not collect data merely because it may be useful one day. Every field increases operational and governance work.
6. Integrations and external services
Name the systems that exchange data with the application and define the business purpose of each connection. The specification should cover more than the successful transfer.
For each integration, record:
- the data sent and received;
- the direction and timing of the exchange;
- which system owns the record;
- authentication and account ownership;
- provider limits or dependencies that need confirming;
- what happens when the external service is delayed or unavailable;
- how failures are retried, reconciled and reported;
- who supports the connection after launch.
7. Non-functional requirements
Functional requirements describe what users can do. Non-functional requirements describe the conditions under which the system must operate. They should be proportionate and testable rather than copied from a generic enterprise checklist.
| Area | Questions the specification should answer |
|---|---|
| Performance | Which actions are time-sensitive, under what realistic load, and how will response be measured? |
| Availability | When is the service required, what disruption is tolerable and what dependencies affect it? |
| Security | What needs protection, which threats and roles matter, and where is specialist review required? |
| Accessibility | Which users, standards and testing approach apply to the product? |
| Auditability | Which significant actions must be attributable and reviewable? |
| Backup and recovery | What data must be restored, to what point, within what operational timeframe, and how will recovery be tested? |
| Scalability | What credible growth in users, records or transactions should the first design support? |
8. Privacy, security and specialist-review flags
The business brief should identify the types of information involved, the people affected and the consequence of misuse or loss. It should not invent legal or security conclusions where specialist assessment is needed.
Mark requirements that need current review, for example:
- personal or special-category data;
- payments or financial information;
- high-impact permissions and exports;
- regulatory retention duties;
- identity verification or single sign-on;
- cross-border services or data transfers;
- contractual security commitments;
- public-sector accessibility obligations.
These flags help the project obtain the right advice before decisions become embedded in the build.
9. Environments, migration and launch
Specify how work moves from development to testing and production, and who controls each environment. Define the migration approach, including source data, cleansing responsibility, rehearsal, cutover, validation and rollback.
The launch plan should identify:
- who gives go-live approval;
- what must be checked immediately before and after release;
- how users are trained and informed;
- how urgent defects are handled;
- what conditions would trigger rollback;
- who monitors the system during the early operating period.
10. Acceptance criteria
Every material requirement needs an observable result and a method of verification. Avoid subjective wording such as “easy to use”, “fast” or “secure” without explaining what evidence will be accepted.
| Weak wording | More useful wording |
|---|---|
| The manager can approve applications. | A user with the Manager role can approve a submitted application assigned to their team; the status changes to Approved, the decision and timestamp are recorded, and the applicant receives the agreed notification. |
| The report must be fast. | The monthly operations report for the agreed test dataset is displayed within the agreed response threshold under the defined test conditions. |
| Users cannot see other customers' data. | Test accounts from one customer organisation cannot view, search, export or access by direct URL any record belonging to another customer organisation. |
Acceptance should cover failures and permissions as well as the normal journey.
11. Ownership, handover and support
Define the assets the business must control and the evidence required at handover. Depending on the project, this may include:
- domain and DNS access;
- source repositories and revision history;
- cloud and deployment accounts;
- databases, storage and backups;
- provider accounts, licences and billing access;
- keys and secrets transferred through an appropriate process;
- technical and operational documentation;
- known issues and support procedures;
- data-export and supplier-exit arrangements.
Also state what support is included after launch, how incidents and change requests are submitted, and which response expectations require a separate agreement.
12. Assumptions, dependencies and open questions
Do not hide uncertainty inside the estimate. Record what the supplier is assuming, what the business must provide and which decisions remain open. Give each open question an owner and a date or project stage by which it must be resolved.
This is especially useful for incomplete third-party documentation, uncertain data quality, provider approvals and policies that are still being agreed.
How detailed should the specification be?
The right level of detail depends on commercial and delivery risk. A small discovery engagement can begin with a concise brief and produce a more detailed backlog. A fixed-price procurement or business-critical migration normally needs stronger definition before commitment.
The test is not document length. The test is whether important users, rules, data, exceptions, dependencies and acceptance decisions are visible. Hundreds of low-value statements do not compensate for one unspoken critical assumption.
A practical preparation process
- Describe the current problem and intended outcome.
- Map the current process with the people who perform it.
- Identify roles, records, systems and exception paths.
- Separate the first release from later ideas.
- Write testable requirements and acceptance criteria.
- Mark legal, security, privacy and provider questions for current review.
- Ask operational users and decision-makers to challenge the draft.
- Have shortlisted suppliers identify assumptions, exclusions and unresolved risks.
- Update the specification as decisions are made and retain a controlled version.
Questions to ask a supplier
- Which parts of the brief are assumptions rather than confirmed scope?
- What discovery work is required before a reliable estimate is possible?
- Which third-party services, licences and ongoing charges are expected?
- How will permissions, integrations, migration and exception paths be tested?
- Which assets and accounts will the business control throughout the project?
- What documentation and handover are included?
- How are changes to the agreed specification assessed and approved?
- What is excluded from support after launch?
Next step
Begin with one representative process and write it from trigger to outcome. Add the roles, records, decisions, exceptions and acceptance evidence. If that section cannot be made clear, the project is not ready for a reliable build estimate, regardless of how polished the proposed screens appear.