Project management

How to write a requirements specification for a software or web project

By Codevista InnovationsPublished 12 October 20268 min read

A good software requirements specification describes the need, not the solution: who the users are, what they must be able to do, what conditions define a feature as done, and the constraints it must respect (security, hosting, languages, budget, deadlines). It fits into eight sections, from business objectives to code ownership and maintenance. Written well, it becomes a shared reference for client and supplier, then carries on as an agile backlog once the project is under way.

What is a requirements specification for in a web project?

A requirements specification turns a business need into expectations a development team can understand. For senior management or the IT department, it is the tool that lets you compare bids, estimate a realistic budget and run the project without misunderstandings.

It protects the client: without a reference document, it is hard to show that a feature is missing or that a delivery does not conform. It also protects the supplier: a written scope keeps unpriced extra requests in check.

Once the document is ready, our guide to choosing a software development company in Casablanca covers the questions to put to shortlisted firms.

How should a software requirements specification be structured?

Here is a standard outline, to be scaled to the size of the project. Start with the why before the what, and the what before the how.

1. Background and objectives: the current situation, the problem to solve, and the business indicators the organisation will track itself to judge the result (time to process a case, data-entry errors, tasks still done by hand).
2. Users and personas: who will use the tool (customers, sales staff, back office, managers), on which device and in which language.
3. Functional scope: the needs written as user stories, each with its acceptance criteria and priority.
4. Non-functional requirements: performance, security, accessibility, hosting, languages.
5. Integrations: ERP, CRM, email, online payment gateway, single sign-on (SSO), partner APIs.
6. Data and migration: existing data to be carried over, its quality, retention periods and the personal data involved.
7. Constraints, budget and timeline: a budget range, a hard or preferred deadline, regulatory or internal constraints.
8. Deliverables, ownership and maintenance: what is handed over, who owns the code and the intellectual property, how the software will be maintained.

A few well-organised pages beat a hefty document nobody reads. Attach mock-ups and screenshots of the existing system as appendices.

How to describe features: user stories and acceptance criteria

The most effective format is the user story: “As a [user], I want [action] so that [benefit]”. It forces you to say who has the need and why.

Each story comes with acceptance criteria: testable conditions that settle, without argument, whether the feature is done. For example, for a leave request:

• the employee sees their remaining balance before submitting the request;
• the manager receives a notification and can approve or reject it with a comment;
• a request that overlaps an already approved period is blocked with a clear message.

Give each story a priority, for instance using the MoSCoW method (Must, Should, Could, Won't: essential, important, nice to have, out of scope for this release). That is what lets you make trade-offs if the budget tightens and define a first release that people can genuinely use.

Non-functional requirements: security, performance, languages and hosting

Often overlooked, these requirements are expensive to retrofit. Describe the level you expect, not a technology.

• Performance: expected concurrent users, acceptable response times on critical screens, use over mobile networks.
• Security: roles and permissions, authentication, logging of sensitive actions, backups and restore. Also ask the supplier how it protects your data on its side; ISO/IEC 27001 certification is one indicator, as our article on data security at a software supplier explains.
• Personal data: in Morocco, its processing is governed by Law 09-08 (loi 09-08), the national data protection law. Filings with the CNDP, the Moroccan data protection authority, are the responsibility of the data controller, normally the client company; specify what the supplier must provide to prepare them (purposes, categories of data, security measures).
• Accessibility: contrast, keyboard navigation, screen-reader compatibility; the W3C's WCAG guidelines provide a common vocabulary for setting the expected level.
• Hosting: cloud or on-premises servers, data location if it is mandated (transferring personal data outside Morocco is also regulated by Law 09-08), acceptance-testing and production environments.
• Languages: French, Arabic, English, even Amazigh. Arabic requires a right-to-left (RTL) interface: mirrored layout, suitable typography, fields mixing Arabic text and numbers. Planned from the start, it is a design decision; bolted on at the end, it is a whole workstream.

Integrations, data and migration: the part everyone underestimates

Business software rarely lives on its own. For each system to be connected, state what it needs to exchange, in which direction and how often, who the technical contact is, and whether API documentation and a test environment exist. An integration whose vendor does not respond can stall an entire project: better to find out before you sign.

Data migration deserves the same care. List the sources (Excel files, a legacy application, an existing database), assess their quality honestly (duplicates, empty fields, inconsistent formats) and say who is responsible for cleaning them. Plan at least one dry-run migration in the acceptance-testing environment before the real cutover, and a rollback plan in case it fails.

Budget, deadlines, deliverables and code ownership

Many organisations are reluctant to state a budget. Yet a budget range lets suppliers propose a suitable solution rather than bids that cannot be compared. Also distinguish between a hard deadline and a preferred date.

The deliverables section must remove any ambiguity:

• handover of the source code in a repository the organisation holds the access to;
• intellectual property in the code developed for you, and the terms of use for reused or open-source components; do not assume that paying for development makes you the owner, get the assignment of rights put in writing;
• technical documentation, plus access to the hosting accounts, and domain names registered in the organisation's name;
• maintenance terms: bug fixes, enhancements, response times, and reversibility if you change supplier.

These clauses belong in the contract: have them reviewed by a lawyer rather than relying on a generic template.

Fixed specification or agile backlog: how to combine the two?

A fixed-price specification that freezes the entire scope reassures procurement, but it assumes every need is known in advance, which is rarely the case. Conversely, a backlog with no written framework leaves the client with no budget safeguard. The combination that works:

1. freeze in the document what must not change: objectives, users, non-functional requirements, budget, deadlines, deliverables and ownership;
2. express the functional scope as prioritised user stories, which become the initial backlog;
3. plan a discovery phase to refine the top-priority stories;
4. validate each iteration in an acceptance-testing environment, and handle every new request by swapping out a lower-priority story.

This is how Codevista Innovations runs its development projects: a discovery and design (UX/UI) phase, then two-week sprints with regular deliveries to a staging environment for validation. If you are unsure how to keep that backlog alive, our comparison of Scrum vs Kanban will help you choose.

On the client side, the person leading the project has to manage scope, risks and stakeholders: precisely the areas covered by the PMP® training, which prepares for PMI certification.

Common mistakes in an application requirements specification

• Describing a solution instead of a need: “an Excel button in the top right corner” rather than “HR must be able to use the history in their own tools”. The supplier can no longer propose something better.
• Not prioritising: when everything is essential, nothing is, and the first budget trade-off turns into a dispute.
• Leaving out acceptance criteria: acceptance testing becomes an argument over interpretation.
• Writing it alone: a document written by IT without the business teams, or the other way round, misses some of the constraints.
• Stopping at go-live: without hosting, maintenance and reversibility spelled out in black and white, the delivered software quickly becomes a dependency you are stuck with.

Would you like an outside view of your requirements specification, or help scoping a future custom SaaS project? The Codevista Innovations team in Casablanca is happy to talk it through: get in touch.

Frequently asked questions

What is the difference between a functional and a technical specification?

The functional specification describes what the software must allow users to do, for which users and against which acceptance criteria. The technical specification describes how it will be built: architecture, technologies, data model, hosting. The client writes the first; the supplier usually produces the second, approved with the IT department.

How many pages should a requirements specification for a web application be?

There is no ideal length: a simple internal tool fits into a few pages, while a platform with many integrations needs more. The right test is verifiability: every expected feature must be identifiable, prioritised and backed by acceptance criteria. Short and reviewed by the business teams beats long and ignored.

Should I state my budget in the requirements specification?

Yes, at least as a range. Without one, suppliers size their bids very differently and the proposals become impossible to compare. A range lets each of them propose what is realistic and suggest splitting the work into successive releases. Also state whether the budget covers maintenance and hosting after go-live.

Is a requirements specification compatible with Scrum?

Yes, as long as you do not freeze everything. The document sets the objectives, users, non-functional requirements, budget, deliverables and code ownership. The functional scope, written as prioritised user stories, becomes the initial Product Backlog, which the Product Owner orders and the team refines sprint after sprint. Each new request is weighed against the existing stories, which keeps the budget under control.