How to Write an SRS Document With a Real Example

An SRS, or software requirements specification, is one plain document that says exactly what software should do, so developers, testers, and clients all build and check the same thing. I have seen teams skip it and then argue for weeks about a feature that was never written down. In this guide I will show you how to write one, using a real login feature as the example, because login is something every team has built and almost every team has got wrong at least once.

What an SRS Is (and What It Is Not)

An SRS is a working agreement. It lists what the system must do, what it must not do, and how we will know it is done. It is not a design document, so it does not tell developers which framework to use or how to structure the database. It is not a marketing page either, so it does not promise things the team has not agreed to build. When I write one, I keep asking a simple question: could a new developer read this on Monday and build the feature without guessing? If the answer is no, the SRS is not finished yet.

A good SRS also protects the client and the team. The client can point to it and say this is what I asked for, and the team can point to it and say this is what we agreed to build, and this is what a change will cost. I have watched projects go sideways when that agreement lived only in chat messages. Nobody could find the decision, and everybody remembered it differently.

What to Include in an SRS

Keep the structure simple. I use the same skeleton for most projects, and I only add sections when the project actually needs them. A short SRS that people read beats a long one that nobody opens.

Start with the purpose and scope. Say in two or three sentences what this document covers and what it leaves out. Then describe the users. A login feature has at least two users, a regular user who signs in, and an admin who resets passwords and locks accounts. Write down what each one can do.

Then come the requirements themselves, split into functional and non-functional. Functional requirements say what the system does, for example a user can sign in with an email and password. Non-functional requirements say how well it does it, for example the login page must load in under 2 seconds on a normal connection. Both matter, and I will show you both in the login example below.

Add the edge cases and the acceptance criteria. Edge cases are the moments that break a feature in real life, like a wrong password, an expired reset link, or an account that is already locked. Acceptance criteria are the checks that prove the feature works, written so a tester can tick them off one by one. Finish with a short glossary if your project has words that mean different things to different people, because a word like user, account, or session causes more confusion than most teams expect.

How I Write an SRS, Step by Step

I never start by writing the document. I start by talking to the people who will use the feature, and I write down their answers in plain language. For login, I ask who signs in, how often, what happens when they forget a password, and what the team should do when someone tries the wrong password ten times in a row. Those answers become the first draft of the requirements, and I am always surprised how many gaps appear in that first conversation.

Next I write the happy path, the normal flow when everything works. A user opens the login page, enters an email and password, and reaches the dashboard. Then I write the unhappy paths, because that is where most SRS documents fail. Wrong password, locked account, expired reset link, a user who is already signed in on another device. I write each one as a short paragraph first, then I turn it into a requirement with a number.

Then I add the numbers. A requirement without a number is a wish, and wishes are hard to test. I do not write that login should be fast. I write that it should respond in under 2 seconds for 95 percent of attempts. I do not write that passwords should be secure. I write the exact rules, like at least 8 characters, and a lockout after 5 failed attempts in 15 minutes. Numbers make the SRS testable, and they stop arguments later, because the team agreed the number before the code was written.

Finally I share the draft with one developer and one tester before I share it with the client. The developer spots the parts that are impossible or unclear, and the tester spots the parts that cannot be checked. I fix those two rounds of feedback first, and only then do I call the document ready. That extra day of review has saved me from more rework than any template ever has.

Here is the example I promised, written the way I would write it for a real client. The feature is email login for a small web app, with password reset and account lockout. Read it as a template you can copy, and change the numbers to fit your own project.

Functional requirements, or what the system must do. A user can sign in with a registered email address and password. A user can request a password reset link by email, and that link works once and expires after 1 hour. A user can sign out from all devices from the account settings page. An admin can lock an account, unlock it, and reset a password for a user who cannot use email. After 5 failed login attempts in 15 minutes, the account locks for 30 minutes, and the user sees a clear message that says when to try again.

Non-functional requirements, or how well it must work. Security first, because login is the front door. Passwords are stored hashed, never in plain text, and reset links expire after 1 hour and work only once. The login page loads in under 2 seconds on a standard broadband connection, and the login request answers in under 2 seconds for 95 percent of attempts. For usability, error messages say what went wrong in plain words, like wrong email or password, and they never say whether the email or the password was the wrong one, because that detail helps attackers. The login form works on a phone screen without sideways scrolling, and it works with a keyboard alone.

Acceptance criteria, or how we will know it is done. A tester can sign in with a correct email and password and reach the dashboard in under 2 seconds. A tester who enters a wrong password 5 times in 15 minutes sees the account locked, and cannot sign in with the correct password until 30 minutes have passed. A tester who requests a reset link, waits 61 minutes, and clicks it sees that the link has expired. A tester who uses a reset link twice finds that the second use fails. An admin can lock an account and the user sees a clear message on the next sign in attempt. If all of those pass, the feature is done. If one fails, it is not, and that is the point of writing the criteria down before the work starts.

Common Mistakes I Have Seen

The first mistake is vague words. I have read SRS documents that said the system should be fast, user friendly, and secure, and none of those words meant the same thing to the client and the developer. Fast to one person was 1 second, and to another it was 5 seconds. Replace every vague word with a number, a time, or a concrete check, and the document gets useful at once.

The second mistake is missing edge cases. Teams write the happy path and stop, and then the first real user forgets a password, or types an old email, or tries to sign in twice, and nobody agreed what should happen. I now write the unhappy paths first for login, because they are where users actually get stuck, and where support tickets come from.

The third mistake is no acceptance criteria. Without them, testing becomes a matter of opinion, and the client and the developer argue about whether a feature is finished. A short list of checks at the end of each feature section ends that argument before it starts, and it gives the tester something real to work with.

The fourth mistake is copying a template and filling in the blanks. A template can help you remember the sections, but it cannot tell you what your users need. I have seen SRS documents that were 30 pages long and still did not say what happened after 5 failed logins. Start from the user and the real flow, and use the template only to check that you have not missed a section.

Before I send an SRS to a client, I run through a short list. Can a new developer build the feature from this document without asking me a question? Does every requirement have a number, a time, or a clear check? Are the edge cases written down, including wrong passwords, expired links, and locked accounts? Does every feature have acceptance criteria a tester can tick off? Have one developer and one tester read it and found nothing unclear? If I can answer yes to all five, I send it. If I cannot, I fix the no first, because a client will find that gap in the worst possible week.

How to Write an SRS Document With a Real Example