How to Write a Software Requirements Document: A Guide with Examples

A software requirements document defines what a piece of software must do, which rules it must follow, and when it counts as "done." A good requirements document doesn't have to be long or formal. It just needs to be something everyone reads the same way: user stories, clear acceptance criteria, business rules, and non-functional requirements. In this guide we walk through the sections of a requirements document and share examples you can reuse.

Brief vs. requirements document

A project brief gives short answers to "why" and "what": it describes the problem, the users, the goals, and the constraints. A requirements document answers "exactly how should it behave?" The brief usually comes before you request proposals; the requirements document comes after the scope is settled, often written together with the development team.

That distinction matters. Writing a highly detailed requirements document on your own, without talking to the team, can lock in decisions that are technically hard or unnecessary. The best results come from a joint effort where the business knowledge comes from you and the technical judgment comes from the team.

Sections of a software requirements document

1. Purpose and scope

Describe which release the document covers and where its boundaries are. Stating what's out of scope is just as important as the scope itself: "This release doesn't include payment collection; payments will be tracked manually via invoices."

2. User roles

Define every role that will use the system and its permissions. For example: Admin, Sales Rep, Dealer. A short table showing what each role can see and do prevents authorization bugs from the start.

3. User stories

User stories are the clearest way to write functional requirements. The pattern looks like this:

As a [role], I want to [action] so that [goal].

Example:

As a dealer, I want to see the current stock level of every product in the product list so that I know what's available.

This pattern also conveys who the feature is for and why it exists. When the team knows the goal, they can propose better solutions.

4. Acceptance criteria

Every user story should have concrete conditions that show it's done. A common pattern is Given / When / Then:

• Given the dealer is logged in,
• When they open the product list,
• Then the current stock quantity should appear next to each product,
• And if stock is zero, the product should be labeled "out of stock" and can't be added to the cart.

Acceptance criteria clarify both what the developer will build and what you'll test. Instead of unmeasurable phrases like "it should be user-friendly," write conditions that can be verified.

5. Business rules

Collect rules that affect multiple stories in a separate section. Examples:

• Once an order is approved, only an admin can cancel it.
• When a dealer exceeds their monthly credit limit, new orders go into an approval queue.
• Prices are shown excluding VAT; VAT is calculated separately in the cart.

Keeping business rules separate prevents the same rule from being written differently in different places.

6. Data and integrations

Describe what data the system will hold (for example customers, products, orders) and which external systems that data comes from and goes to. For each integration, specify the direction and frequency of the data flow and what happens when something fails.

7. Non-functional requirements

These are expectations about how the system works rather than what it does:

• Performance: Frequently used screens should load within an acceptable time.
• Security: Password policy, two-factor authentication, session length.
• Accessibility: Keyboard navigation, sufficient color contrast.
• Browser and device support: Which browsers and screen sizes will be supported.
• Language: Is the interface in one language, or several?
• Data retention and privacy: Retention periods, deletion and export needs (in Turkey, under KVKK, the national data protection law).
• Backups: Backup frequency and restore expectations.

This section is often forgotten, and it tends to cause surprises right before launch.

8. Wireframes

Wireframes or simple screen sketches are understood faster than long descriptions. Link each sketch to the related user stories.

9. Open questions

Keep undecided topics in a list and assign an owner to each. Making open questions visible instead of hiding them stops the project from moving forward on wrong assumptions.

A copy-and-paste requirements template

You can use this structure for every feature:

• Feature name:
• User story: As a [role], I want to [action] so that [goal].
• Priority: Must have / Should have / Could have
• Acceptance criteria: Given... When... Then...
• Related business rules:
• Related wireframe:
• Open questions:

Example: a filled-in requirement

Here's what the template might look like in practice, using a dealer portal as an example:

• Feature name: Placing an order
• User story: As a dealer, I want to add products to a cart and submit the order so that I can order without having to phone it in.
• Priority: Must have
• Acceptance criteria:
  • Given the dealer is logged in and has at least one product in the cart, when they click "Submit order," then the order should be created with the status "Awaiting approval" and the dealer should see the order number.
  • Given a product in the cart sold out while ordering, when the dealer tries to submit the order, then the system should show which product is out of stock and not create the order.
  • Given an order has been created, then a notification email should go to the sales team.
• Related business rules: Monthly credit limit rule, VAT display rule.
• Related wireframe: Cart screen and order confirmation screen.
• Open questions: Can a dealer cancel their own order while it's awaiting approval? Owner: sales manager.

Even an entry this short makes clear what the developer will build, what the tester will check, and which decision is still pending.

Common mistakes when writing requirements

• Prescribing the solution: Saying "the user should be able to pick one of five options" instead of "add a dropdown" leaves the team room to propose a better interface.
• Skipping edge cases: "The user places an order" says nothing about what happens if stock runs out, payment fails, or the user abandons the flow halfway.
• Freezing the document: Requirements get clearer as the project goes on. Recording changes in the document with version notes keeps it current.
• Not getting buy-in from everyone: Have the people who'll use the system day to day read the document too; they know the actual workflow best.

Where and how to keep the document

Keep the requirements document somewhere everyone can access, with a single current version. File versions bouncing around by email create confusion about which decision is the valid one. A shared document, a project management tool, or a docs folder in the code repository all work. What matters is that you can see who changed what and when, and that the approved scope is clearly marked.

Conclusion

A good software requirements document tells the development team what to build and tells you what to test. User stories, clear acceptance criteria, business rules kept in one place, and non-functional requirements that don't get forgotten prevent most of the misunderstandings in a project. At Weras Labs, we clarify scope in a structure close to this one during the written proposal stage, and throughout development we verify acceptance criteria together through preview links; details are on our services page.