How to Create a Software Requirements Document

A project brief gets you comparable quotations. A requirements document gets you a system that matches your business. They are different documents written at different moments, and conflating them is the most common documentation error in Nigerian software projects.

This guide covers the second document: what belongs in it, how to write requirements that survive contact with a development team, and how to control changes once the build has started.

What a requirements document is and who writes it

Definition: A software requirements document, often called a requirements specification or SRS, is the agreed description of what a system must do and the conditions under which it will be accepted. It is the reference point for building, testing and settling disputes.

Who writes it depends on your situation:

The most reliable arrangement for a Nigerian SME is a short paid discovery phase in which the vendor writes the document with you, and you retain ownership of it. That way it can be used for a second opinion, a competitive quotation or a different vendor later.

The structure of a usable requirements document

Length follows complexity. A departmental tool might need fifteen pages; a multi-role operations platform might need sixty. Neither length is impressive on its own. Testability is what matters.

How to write a requirement that can be built and tested

Use one consistent sentence pattern and number every statement.

Pattern: "REQ-042: The system shall allow an authorised branch manager to approve a credit sale up to ₦500,000, recording the approver, the amount and the timestamp."

Four qualities make a requirement usable:

• Specific. "Fast" is not specific. "Search results return within three seconds on a 3G connection" is.
• Testable. Someone can demonstrate it working or failing without argument.
• Atomic. One requirement per statement. Sentences containing "and also" usually hide two requirements.
• Free of solution. Say what must be achieved, not which library to use, unless you have a genuine constraint.

Attach acceptance criteria to anything complex:

• REQ-042 acceptance: A branch manager approves a ₦450,000 credit sale successfully. The same manager is blocked at ₦550,000 with a clear message. The approval appears in the audit log with user, amount and time. A sales officer without approval rights cannot see the approval action at all.

Write acceptance criteria before the build, not after. They are the difference between "it works" and "it works the way our business needs".

Functional requirements: the rules of your business

Functional requirements describe behaviour. Group them by process rather than by screen, because screens change and processes do not.

Typical groups for a Nigerian operations system:

• Access and accounts. Registration, login, password reset, deactivation of departed staff.
• Master data. Creating and editing customers, products, prices, branches.
• Core transaction. Order, booking, admission, loan application, dispatch: the thing the business actually does.
• Approvals and exceptions. Discounts, credit limits, refunds, cancellations, overrides and who may perform them.
• Money. Payment capture, confirmation of bank transfers, reconciliation, receipts, invoices.
• Notifications. Who is told what, through which channel, and what happens if delivery fails.
• Audit. What actions are recorded and for how long.

Pay particular attention to exceptions. Most requirements documents describe the happy path in detail and leave the failure paths undefined, which is precisely where expensive disagreements arise. For every core transaction, state what happens when it is cancelled, reversed, duplicated, abandoned midway or performed by someone without authority.

Non-functional requirements: the targets everyone forgets

Non-functional requirements describe how well the system must perform. They are frequently omitted, then discovered as problems after launch.

Set each target at a level you can justify. Demanding 99.99% availability from a modest build will raise cost substantially and is usually unnecessary for an internal business system.

Roles and permissions: the matrix that prevents disputes

A permissions matrix is one table and it eliminates a whole class of arguments.

Build this table with the people who actually perform the work. It routinely reveals that two departments believe they own the same approval, which is a business problem worth solving before it becomes a software problem.

Data, integrations and reporting

Data. List the main records and their essential fields, especially anything unusual to your business. State which fields are mandatory, which must be unique, and what validation applies. Include retention: how long records are kept and what happens at the end of that period.

Migration. State what historical data moves into the new system, in what condition it currently exists, and who is responsible for cleaning it. Migration is a project in its own right and belongs in the document.

Integrations. For each one, specify:

• The external system and, where relevant, the provider, such as a payment gateway or accounting product.
• Direction of data flow and frequency.
• What triggers the exchange.
• What happens when the integration is unavailable: queue, retry, alert or fail visibly.
• Who holds the credentials.

Reporting. List each report with its purpose, audience, fields, filters and frequency. "Management reports" as a phrase is unbuildable. Five named reports with defined columns are straightforward.

Assumptions, constraints and what is out of scope

Assumptions are the things that must be true for the estimate to hold: that branch connectivity will be upgraded, that product data will be cleaned by a certain date, that a payment gateway account exists, that two staff will be available weekly for review sessions. Write them down; when an assumption fails, it explains a delay honestly instead of becoming a dispute.

Constraints are the fixed conditions: an existing accounting system that must remain, a regulatory requirement, a hard deadline, a device standard your staff already use.

Out of scope is the shortest and most valuable section. Examples: "Payroll is not included." "Mobile app for customers is phase two." "Integration with the HMO portal is excluded." Everything unlisted will otherwise be assumed by somebody.

Example (hypothetical): requirements extract for a school management system

Example (hypothetical). A private school group with three campuses in Abuja is commissioning a system for admissions, fees, results and parent communication.

Selected functional requirements:

• REQ-011: The system shall allow an admissions officer to record an application with the pupil's details, intended class and supporting documents.
• REQ-023: The system shall generate a termly fee invoice per pupil based on class, applicable discounts and optional services such as transport.
• REQ-024: The system shall record part payments against an invoice and display an outstanding balance.
• REQ-031: The system shall prevent a result sheet from being published until the class teacher and the head of section have both approved it.
• REQ-047: The system shall send a fee reminder to the registered parent contact through SMS and email, and record whether delivery succeeded.

Selected non-functional requirements:

• The fee balance screen shall load within three seconds on a 3G connection.
• Results and pupil records shall be accessible only to staff with an assigned role, with all views logged.
• Personal data of pupils and parents shall be handled in line with the Nigeria Data Protection Act 2023, and the group will confirm its obligations with the Nigeria Data Protection Commission.
• The system shall support 300 concurrent users during results publication week.

Out of scope: Payroll, library management, transport route optimisation, a mobile app for parents in phase one.

Assumption: Each campus will have a working internet connection with a backup provider before rollout.

Notice that every statement can be demonstrated or refuted. That is the whole test.

What changes for Nigerian businesses

Connectivity belongs in the requirements. State what the system does when the network drops mid-transaction. For branch and field operations, decide explicitly between failing visibly, queuing locally or requiring connectivity. This one decision moves cost more than most features.

Power interruptions. Requirements should cover unsaved work, session timeouts and automatic recovery after a device restarts. Long forms that lose everything at a power cut are abandoned quickly.

Payment confirmation. Bank transfer is widely used and does not confirm itself. Specify how a transfer is matched to an invoice, who confirms it, what evidence is attached and how a mismatch is resolved. Consult your provider's developer documentation, such as Paystack or Flutterwave, for what the platform supports.

Identity and contact data. Customers may share phone numbers, use several numbers, or provide informal addresses. Specify matching rules and allow landmark-based address fields rather than assuming a postcode-based format.

Naira and formatting. State currency formatting, rounding rules for discounts and taxes, and date format. These small rules cause visible errors on invoices when left unstated.

Data protection. Specify consent capture, access control, retention and deletion for personal data, in line with the Nigeria Data Protection Act 2023. Confirm your specific obligations with the Nigeria Data Protection Commission or a qualified adviser rather than relying on a vendor's assurance.

Handover and documentation. Make source code, documentation, deployment instructions and account ownership explicit requirements rather than assumptions, and verify them before final payment.

Sign-off, versioning and change control

1. Version every draft. Date it, number it and name the author. Teams working from three different versions is a real and common failure.
2. Review with the people who do the work, not only managers. Walk through five real scenarios from last month and check the requirements cover them.
3. Sign off formally. A named person on each side, with a date. The signed version becomes the baseline.
4. Attach it to the contract as the scope reference.
5. Log every change request with a number, the reason, the cost impact, the timeline impact and the approver. No verbal changes.
6. Re-baseline at agreed points rather than continuously, so the document remains an accurate description of what is being built.
7. Keep it alive after launch. A maintained requirements document makes the next enhancement, vendor change or audit dramatically cheaper.

Mistakes to avoid

• Describing screens instead of rules. Screens change during design; business rules are what you are actually buying.
• Only documenting the happy path. Cancellations, reversals, duplicates and unauthorised attempts are where systems fail in production.
• Omitting non-functional requirements. Performance, backup and access control become emergencies later if they are not targets now.
• Vague words. "Fast", "user-friendly", "robust" and "secure" cannot be tested. Replace each with a measurable statement.
• Letting the vendor own the only copy. You should hold the document and be able to give it to another firm.
• Skipping the permissions matrix. Access disputes surface at go-live, when they are most disruptive.
• No change log. Untracked changes make it impossible to explain later why the system does what it does.
• Writing it alone in an office. Requirements gathered without the people performing the process describe an imaginary business.

Requirements document checklist

• Purpose and scope stated in one paragraph
• Business terms defined once
• All user roles listed
• End-to-end process described before requirements
• Every requirement numbered, atomic and testable
• Exception and failure paths covered for each core transaction
• Non-functional targets set for performance, availability, backup, security and audit
• Permissions matrix agreed with the departments involved
• Data fields, validation and retention documented
• Migration responsibility and data condition stated
• Each integration specified with failure handling
• Reports listed with fields and audience
• Assumptions and constraints written down
• Out-of-scope list explicit
• Acceptance criteria defined for complex requirements
• Version, sign-off and change-control process agreed

Conclusion

A requirements document earns its place by making disagreement cheap. Write numbered, testable statements about behaviour rather than screens. Cover the failure paths, not just the successful ones. Set non-functional targets you can justify. Agree a permissions matrix with the departments involved. Write down assumptions, constraints and exclusions, and control changes through a numbered log.

Do that, and acceptance becomes a demonstration rather than an argument, and the document keeps paying you back every time you enhance the system, change vendor or explain to a new manager why the system behaves the way it does.

If you are about to commission a custom system and want the requirements defined properly before development begins, Linestech can run the discovery and produce a specification you own and can take to any developer.

Frequently asked questions

What is the difference between a project brief and a requirements document?

A brief is written before you engage anyone and exists to obtain comparable quotations; it describes intent, scope boundaries and budget. A requirements document is written during or after engagement and defines precisely what will be built and how it will be accepted. The brief informs the proposal; the requirements document governs the build.

Do agile projects still need a requirements document?

Yes, though it takes a different shape. Agile teams typically maintain a backlog of user stories with acceptance criteria rather than a single frozen specification, but the underlying content, business rules, permissions, non-functional targets and exclusions, is the same. What changes is how often it is updated, not whether it exists.

How long should a requirements document take to produce?

For a departmental system, one to three weeks including review sessions. For a multi-role operations platform, four to eight weeks. The main constraint is the availability of the staff who understand the process. Rushing this stage is a false economy because ambiguity surfaces later as rework.

Should I pay a vendor to write my requirements?

Often yes, through a short paid discovery phase, provided you retain ownership of the resulting document and can use it for competitive quotations. Free requirements work is usually shallow, since the firm doing it is absorbing cost, and shallow requirements produce optimistic estimates.

How do I handle requirements that change during the build?

Expect some change and plan for it. Use a numbered change request for each one, with its cost and timeline impact stated before approval, and a single decision-maker on your side. Batch smaller changes into an agreed review point instead of interrupting the team continuously.

Who should sign off the document?

One named person on your side with real authority, supported by the heads of each affected department, plus the vendor's project lead. Sign-off by committee without a single accountable name is how documents get approved that nobody has actually read.

What if the developer says my requirements are impossible?

Ask which specific requirement, why, and what alternative achieves the same business outcome. Some requirements are genuinely unrealistic within the budget; others are simply unfamiliar. A good vendor will propose an alternative rather than refuse, and the conversation usually improves the requirement.

Can a requirements document reduce the cost of a project?

It can reduce waste rather than the headline price. Clear requirements lower the amount of rework, shorten testing, reduce disputes and make competitive quotations meaningful. They also allow you to cut scope deliberately, which is the only reliable way to reduce cost without reducing quality.

Sources and further reading

Figures, platform rules and regulations change. These are the primary references behind this article and the places to check before you act on it.

• Nigeria Data Protection Commission (NDPC)
• Paystack developer documentation
• Flutterwave developer documentation