Web Development

How to Write a Software Requirements Document Developers Can Use

A practical structure for a requirements document: an eight-part outline, user stories, acceptance criteria, non-functional requirements in plain numbers, and what to leave out.

How to Write a Software Requirements Document Developers Can Use

A software requirements document does not have to be long or formal. It has to let a developer who has never met you understand what to build, who it is for, and how both of you will know when it is done. Most documents we are sent manage the first, some the second and very few the third, which is why quotes for the same project vary so widely and why "that is not what I meant" turns up halfway through so many builds.

This is the structure we ask clients for, written for the person who knows the business, not for an engineer. A word processor is all you need.

A short outline for a software requirements document

The document has three jobs: it lets a team estimate the work, it tells them what to build, and it gives you something to test against at the end. Eight sections are enough for all three:

1. Purpose and background
2. Users and roles
3. Scope: in, out and later
4. Features, as user stories with acceptance criteria
5. Data and integrations
6. Non-functional requirements
7. Constraints and assumptions
8. Open points

Section 1 is half a page: what the business does, what problem this software solves, and what success looks like a year from now. Section 3 is three lists, and the "out" list matters as much as the "in" list, because it prevents arguments later. Section 7 holds the fixed points: a launch date tied to an event, a system you must keep, a budget range. Section 8 is where you write down what you have not decided. Listing an undecided point is far better than hiding it.

The rest of this guide covers the sections that need the most care.

Describe users and problems before features

Start with people. List each type of user (customer, dispatcher, manager, administrator), roughly how many there are, what device they use and what they are trying to get done. Then describe how the work happens today, step by step, including the spreadsheet, the phone calls and the part everyone complains about.

This reads like background, and it is the most valuable page you will write. A feature list says "add a notes field to orders". The problem behind it might be "drivers arrive without the gate code". A developer who knows the problem can suggest showing the gate code on the driver's delivery screen, which a notes field would not have achieved.

Write features as user stories

A user story is one sentence in a fixed pattern:

As a [type of user], I want to [do something], so that [reason].

For example: "As a warehouse supervisor, I want to mark an order as partly shipped, so that the customer can see which items are on the way." The pattern puts three things on the page that feature lists leave out: who does it, what they do and why it matters. The "why" lets a developer choose a sensible design, and lets you cut the story later if the reason turns out to be weak.

Some habits keep stories useful:

  • One action per story. "Manage orders" is a whole module. "Cancel an order before it ships" is a story.
  • Describe the need and leave the mechanism open. "I want to find a customer quickly" is better than "I want a dropdown with autocomplete", unless you really have decided.
  • Give each story a priority: must have for launch, should have, or can wait. If everything is a must, the estimate will tell you so.

Add acceptance criteria to every story

Acceptance criteria are the conditions under which you will agree a story is finished. They turn an opinion ("it should handle partial shipments properly") into something that can be checked. For the story above:

  • Given an order with three items, when the supervisor marks two as shipped, the order status becomes "Partly shipped".
  • The customer receives one email listing the two shipped items and the one still to come.
  • An item cannot be changed back to unshipped once the carrier has collected it.
  • Only users with the Supervisor role see the option.

Notice what the criteria pulled out: an email nobody had mentioned, a rule about reversing a step, and a permission. Each of those is work. Without them written down, the developer would have to guess or ask, and the estimate would be a guess too.

Cover what happens when things go wrong as well as when they go right: the payment fails, the file is too large, two people edit the same record. State numbers and rules exactly: "orders above the customer's credit limit need a manager's approval", not "large orders need approval".

State non-functional requirements in plain numbers

Non-functional requirements describe how well the system must work, as opposed to what it does. They are the ones most often missing, and they can change the cost of a project more than any single feature. You do not need technical language. You need answers like these:

AreaWhat to answerA usable statement
CapacityHow many people use it at the busiest time?"Up to 200 staff signed in on Monday mornings"
SpeedWhat must feel instant?"Customer search returns results within two seconds"
AvailabilityWhen must it be up?"Needed 7 a.m. to 7 p.m. on weekdays. Maintenance can happen at night"
Security and accessWho may see what? Must changes be traceable?"Managers see their own branch only. Every price change is logged with user and time"
PrivacyWhat personal data is stored, where and for how long?"Customer records are kept for six years and hosted in the EU"
AccessibilityDoes it have to meet a standard?"Customer-facing pages are built and tested to WCAG 2.2 level AA"
BackupHow much data could you afford to lose?"No more than one hour of entries"

If you have no standard in mind, two public references help you ask for the right thing: the W3C's WCAG guidelines for accessibility, and the OWASP Application Security Verification Standard, a list of security requirements a team can build and test against. Where a law or a regulator sets the rules for your data, name it in the document and confirm what it requires with your own counsel.

List the data and systems it must work with

Integrations and data imports are where estimates go wrong most often, because they depend on things outside the new system. For each one, write down:

  • the system's name, and who manages your account there;
  • what should move, in which direction and how often ("new orders reach the accounting package within five minutes");
  • whether it offers an API (a documented way for other software to exchange data with it), with a link to that documentation if you have one;
  • for data you want imported: where it lives now, roughly how many records, and a sample file with the real column names.

A sample export tells a developer more in a minute than a page of description, including how clean the data is.

What to leave out

  • Technical decisions you have no reason to fix. Unless your IT team requires a particular language, database or host, describe the need and let the developers propose the technology. A real constraint belongs in section 7, with the reason.
  • Screen layouts described in words. "A blue button in the top right" belongs in a sketch. Rough wireframes of the main screens, even photographed pencil drawings, beat paragraphs.
  • Adjectives that cannot be tested. "User-friendly", "modern", "fast" and "secure" mean something different to every reader. Replace each with a criterion or a number.
  • Everything you might want one day. Put future ideas in the "later" list, so the team can avoid blocking them, and keep them out of the stories to be estimated.

Writing it yourself or working it out together

If you know your process well and the system is small, you can write this document alone and send it out for quotes. Our guide to writing a project brief that gets accurate quotes covers the shorter version you send to vendors first, and how to scope an MVP helps with the "later" list.

Ask for help when departments disagree about how the process should work, when the system replaces something old that nobody fully understands, or when you cannot write acceptance criteria because the rules have never been said out loud. A short discovery phase, in which a project manager and a developer interview your team and write the document with you, costs far less than building from a vague one. It is how most of our custom software development projects begin, often with wireframes from our UI and UX designers. If you already have a draft, send it with a quote request and we will tell you what is missing.

Frequently asked questions

How long should a software requirements document be?

Long enough to cover every must-have story with its acceptance criteria, and no longer. For a small internal tool that can be five or six pages. For a customer-facing platform, twenty to thirty is common. Beyond that, move the later phases into a separate document.

Does the document still matter if the team works in an agile way?

Yes. Agile teams still need to know the goal, the users, the priorities and what "done" means. What changes is that the document is allowed to evolve: stories are refined, added and reordered as you learn, with the effect on cost and dates agreed each time.

Should I include my budget?

A range helps more than people expect. It lets a team tell you which stories fit and which should wait, instead of quoting the full wish list and leaving you to cut it. Without one, you tend to receive proposals that cannot be compared.

Add WorldWin Coder to your preferred sources

Add worldwincoder.com as a preferred source on Google, or open this article in your AI assistant to use it as a source.

Swati Priyadrshni
· Founder & CEO at WorldWin Coder

I'm Swati Priyadarshani, Founder & CEO of LMS Advisor and Co-Founder of WorldWin Coder Pvt. Ltd. (est. 2019). Over the last 10+ years, I've helped enterprises build learning platforms that actually get used - not just deployed.

Keep reading

Have something to build, fix or move?

Tell us where you are. A developer reads every inquiry, and you get next steps and a free quote within one business day.