How to Prepare a Web Software Requirements Document: Practical Template

A web software requirements document brings the project’s business purpose, users, processes, business rules, data, integrations, technical quality expectations and acceptance conditions into one shared reference. A useful document does not stop at “membership, reporting and an administration panel.” It explains who needs each capability, under which conditions, which outcome it should produce and how that outcome will be verified.

The client does not need to make every technical decision in advance. The document makes known business needs visible, marks uncertainty and helps product, design, engineering, testing and operations teams work on the same problem.

This guide uses three layers:

1. Project summary: Business goal, users, scope boundaries, assumptions and priorities.
2. Requirement cards: A testable record for each function, business rule, data need or technical quality.
3. Traceability matrix: The relationship between the goal, requirement, design/development work, test and approval.

A small project can keep all three in one working file. A more complex application may separate business analysis, interface, API, data, security and test documentation while preserving the links between them.

Website brief versus web software requirements document

A corporate website requirements document normally focuses on audiences, pages, content, visual direction, forms, languages and project responsibilities. That may not be enough for a web application with accounts, multiple roles, custom calculations, approval workflows, substantial data or system-to-system transactions.

A web software requirements document also defines:

• roles and permission boundaries,
• workflows from trigger to outcome,
• calculation, limit, approval and status rules,
• data fields, sources, ownership and life cycle,
• API and third-party service behaviour,
• failure, exception and recovery scenarios,
• security, accessibility, performance and continuity requirements,
• acceptance criteria and verification methods,
• release scope and change records.

Use the existing website requirements guide when planning a corporate presentation site. Use the more detailed model in this article when the application runs an operational process, shows user-specific data or exchanges transactions with other systems.

Who should prepare the document?

Requirements are not solely the engineering team’s or an executive’s responsibility. Different people contribute according to the source of knowledge:

• Project/product owner: Business goal, priorities, budget boundary and final decisions.
• Process owner: Current workflow, exceptions and operational rules.
• Real users: Daily tasks, obstacles and usage context.
• Business analyst or project manager: Converts information into consistent, prioritised and verifiable requirements.
• Design team: User journey, interaction, content and accessibility impact.
• Engineering/technical team: Feasibility, architecture, data, integrations, security and operational dependencies.
• Test and acceptance owners: Acceptance criteria, test data and approval evidence.
• Legal, information-security or compliance owners: Specialist review where required by the project context.

One person should own the document. Rather than making every decision alone, that owner consolidates conflicting feedback, assigns open questions and protects the approved baseline.

1. State the business goal and success outcome

Do not begin with a screen list. Define why the project exists and which business result is expected to change.

Weak statement:

Build a modern dealer portal.

More useful statement:

Authorised dealers must be able to create order requests using the products and prices assigned to them; the central team must review and manage those requests in one system. The first release must validate the end-to-end replacement of email and spreadsheet request collection for a defined dealer group.

The success outcome does not need to promise an unproven increase in revenue. A first release can measure completed core transactions, data accuracy, manual intervention, completion time, critical failures or user feedback.

Project-summary fields

2. Record scope boundaries and assumptions

A requirements document should show what will not be delivered as well as what will. “Reporting included” can create an expectation of unlimited reports. State which reports, fields, users and export options belong to the first release.

Separate scope into four lists:

• included in the first release,
• candidate for a later release,
• awaiting research or validation,
• explicitly out of scope.

Do not present assumptions as requirements. If “the ERP will provide a real-time stock service” has not been confirmed, create an assumption/dependency record with an owner and validation date rather than stating it as fact beneath the integration requirement.

3. Define roles and permissions

“User” is rarely one role. A customer, dealer employee, dealer manager, operations specialist, finance owner and system administrator should not automatically see or change the same records.

For each role, answer:

• How is the person invited or registered?
• How is identity verified?
• Which organisation, account or records is the person associated with?
• Which data can the role view?
• Which actions can it start, approve, change or cancel?
• Who removes its access, and how?
• Are records required for critical actions?
• Can it act on behalf of another user?

Simple role-permission matrix

This is an illustrative matrix. Actual permissions must follow project risk. Separate administrative privileges may be safer than assuming one administrator should do everything.

4. Describe user flows end to end

User stories provide a concise way to express the role, need and purpose. The GOV.UK Service Manual recommends including the actor, need and goal, and describes acceptance criteria as outcomes used to confirm that a service meets the user need (Writing user stories).

Example user story:

As a dealer user authorised to place orders, I need to see the products and prices assigned to my dealer so that I do not create a request with an invalid product or price.

One story does not describe the whole flow. Add a diagram or numbered scenario containing:

1. starting condition,
2. user input,
3. system validation,
4. business rule or integration,
5. successful outcome,
6. information shown to the user,
7. data recorded,
8. failure and recovery behaviour.

Alongside the happy path, define important exceptions such as unauthorised access, missing data, duplicate transactions, timeouts and third-party service failures.

5. Write functional requirements as requirement cards

A functional requirement states what the system must do. Giving each requirement a unique identifier helps meeting notes, designs, development tasks and tests refer to the same item.

Requirement-card template

Avoid combining several independent behaviours in one sentence. Split “the system saves the order, sends it to the ERP, emails the user and adds it to the report” into verifiable requirements.

6. Record business rules separately from the interface

A business rule describes organisational decision or calculation logic. It can continue to apply even when the interface changes.

Examples:

• Requests above TRY 50,000 require a second approval.
• Cancellation is available only while a request is under review.
• A customer-specific price takes priority over the general price list.
• A user can view only records belonging to the linked organisation.

Record the source, exceptions, decision owner and sample data for each rule. “The discount is calculated automatically” can produce different interpretations unless it states the rate, priority, rounding, tax and currency behaviour.

A decision table is useful when several conditions produce different results:

The real table must be approved by the finance and process owners. This example is not a claim about Kumsal Ajans or a client’s pricing policy.

7. Define data requirements

The data model is not only an engineering decision. The organisation must explain which information is required, correct, sensitive, retainable and reportable.

For each primary data entity, record:

• field name and business meaning,
• data type or format expectation,
• whether it is required,
• source and owner,
• validation rule,
• who can view and change it,
• retention or deletion need,
• whether change history is retained,
• export and migration requirements,
• personal or sensitive-data classification.

Example data-dictionary row:

Retention periods and legal obligations must be established by appropriately qualified people for the project context. A template does not make that legal decision.

8. Describe integration requirements through behaviour

“ERP integration required” does not establish scope. State which event moves which data, in which direction and with which failure behaviour.

An integration record should contain:

• sending and receiving systems,
• transaction and trigger,
• fields and mapping,
• direction of data movement,
• real-time or scheduled operation,
• authentication and access ownership,
• rate or usage limits,
• timeout and retry behaviour,
• duplicate prevention,
• error recording and notification,
• test environment and sample data,
• service-change and version responsibility.

The existence of API documentation does not prove that the integration is ready. Access, permissions, sample responses, error codes, data quality and a test environment should be verified before implementation.

9. Make non-functional requirements measurable

Non-functional requirements state the quality conditions under which the system operates. “Fast, secure, user-friendly and scalable” can express direction, but it cannot be accepted or rejected without measurement.

Performance and capacity

Record:

• expected concurrent and total users,
• transaction and data volume,
• critical pages or APIs to measure,
• target response or completion time,
• test environment and data volume,
• burst-load scenario,
• acceptable failure behaviour.

Do not copy universal values from another project. Select project-specific conditions from the user need, infrastructure, transaction type and budget.

Security and privacy

Create security requirements according to the application’s data, roles and transaction risk. NIST SSDF recommends identifying security requirements, evaluating the risks software may encounter in operation and determining how design and architecture mitigate those risks (NIST SSDF SP 800-218).

Requirement areas can include:

• authentication and sessions,
• role- and record-level authorisation,
• verification of critical actions,
• data protection in transit and storage,
• file-upload constraints,
• security records and incident notification,
• dependency and update management,
• backup and recovery,
• access provisioning and removal,
• security verification scope.

OWASP ASVS can help convert web-application security controls into testable requirements. The applicable sections and verification level should be selected according to risk and contract scope (OWASP ASVS).

Accessibility

Do not add accessibility only after interface approval. W3C WAI recommends including accessibility objectives, responsibilities, resources and monitoring in project planning (Planning and Managing Web Accessibility).

The document can define the target standard and conformance level, covered journeys, keyboard behaviour, focus, form labels and errors, contrast, text alternatives, dynamic content and verification method. Applicable legal requirements need separate assessment by jurisdiction and service type.

Continuity, maintenance and observability

• uptime and planned-maintenance expectation,
• error and performance records,
• owner of critical alerts,
• backup frequency and retention owner,
• recovery objective and test method,
• behaviour during third-party outage,
• distinction between maintenance, defect correction and new development,
• handover of source code, data, accounts and documentation.

The necessary depth depends on system importance. A small internal tool and an application whose outage stops sales or service delivery do not need identical requirements.

10. Add acceptance criteria and verification methods

Write observable conditions that allow each critical requirement to be called complete. The NASA Systems Engineering Handbook describes validated technical requirements as clear, correct, complete and achievable, and emphasises that requirements should be verifiable and traceable to stakeholder expectations (NASA Systems Engineering Handbook). This is not presented as a mandatory standard for commercial web projects; it is a useful requirements-quality principle.

Example acceptance criteria:

• an active and authorised dealer user sees only products assigned to the linked dealer,
• a direct request for another dealer’s record returns an unauthorised result and reveals no data,
• when the price source is unavailable, the interface does not report a successful transaction,
• a successful request receives a unique number and starts its status history,
• the operations role can see the source and creation time,
• the event is verifiable in the agreed test record with user and time information.

Verification can use review, functional testing, user-acceptance testing, automated tests, performance measurement, security assessment or document inspection according to the requirement. One screenshot does not prove the complete behaviour.

11. Build a traceability matrix

Traceability shows why a requirement exists and how it is verified. A small project does not need a heavyweight tool; a simple table may be sufficient.

The matrix should answer:

• Is there a requirement without an owner or business goal?
• Is there design and development work that fulfils it?
• Does every critical requirement have a test?
• Are the test result and acceptance decision recorded?
• Can the team see which items are affected when a goal changes?

NASA’s requirements-writing checklist also recommends bidirectional traceability between requirements and higher-level needs (How to Write a Good Requirement).

12. Manage change with versions and decision records

A requirements document is not written once and forgotten. It also cannot remain a reliable reference if anyone can silently change it.

Each approved version should record:

• version number and date,
• changed requirements,
• reason for change,
• impact on scope, design, data, integration, security, testing, budget and schedule,
• decision maker,
• open questions and target dates.

Assess a new request against the problem and user outcome first. If it expands the approved scope, decide explicitly which item will be removed or how the budget or date changes.

Copyable web software requirements document template

Use these headings in one document, spreadsheet or project-management system:

1. Document owner, version, date and approvers
2. Organisation/process summary
3. Problem and business goal
4. Target users and roles
5. Primary user outcomes
6. Success indicators
7. First-release scope
8. Later release and out-of-scope items
9. Assumptions, dependencies and open questions
10. User journeys and exceptions
11. Functional requirements
12. Business rules and decision tables
13. Data dictionary and data life cycle
14. Integration and API requirements
15. Security and privacy requirements
16. Accessibility requirements
17. Performance and capacity requirements
18. Backup, monitoring and operations
19. Test-data and environment responsibilities
20. Acceptance criteria and verification methods
21. Handover of accounts, code, data and documentation
22. Maintenance, support and change management
23. Traceability matrix
24. Decision and revision log

Common mistakes

Writing the solution as the need

“Build with React” or “use this product” is a technology decision. The actual requirement may be a user scenario, integration, performance, maintainability or team constraint. If a technology is mandatory, record its reason and owner.

Using ambiguous adjectives

“Fast,” “secure,” “easy” and “modern” express intent but do not define a test. Add the user journey, condition, measurement method and acceptance boundary.

Describing only the happy path

Missing data, unauthorised access, service outage, duplicate transactions and user abandonment can expose significant gaps during real use.

Giving every request the same priority

Separate MVP core, release gates, later release and research items. If everything is labelled important, the team cannot make a decision.

Leaving responsibility unclear

Engineering work can stop when no one owns content, test data, integration access, legal copy, acceptance or production support.

Failing to validate with real users

Management expectations can differ from daily work. Review primary scenarios with people who perform the process and add unclear terms to the project glossary.

How detailed should the document be?

Document length does not demonstrate quality. Detail should be proportional to risk, role count, business rules, integrations, data sensitivity and acceptance needs.

The document may provide a sufficient planning baseline when it answers:

• Which user completes which outcome?
• According to which rules does the system behave?
• Which data comes from where, and who uses it?
• How does the application interact with external systems?
• Which quality and risk conditions are mandatory?
• How will the result be tested and accepted?
• How will uncertainty and change be managed?

Not every answer will be final on day one. Record unknowns as “TBD/decision pending” with an owner, resolution date and impact rather than hiding them.

Before finalising the document, clarify the overall web software process and the MVP first-release decision. Then cross-check requirements against the budget areas, integration records and security and maintenance responsibilities.

Conclusion

A web software requirements document is not a feature list; it is a decision system from business goal to acceptance test. The project summary explains the reason and boundaries, requirement cards define expected behaviour, and the traceability matrix shows the design, development and test counterpart of each item.

A good requirement should be necessary, clear, consistent, feasible and verifiable. Making roles, business rules, data, integrations, security, accessibility and operational requirements visible early allows proposals to be compared against the same scope and project changes to be managed with their consequences.