Software Requirements Specifications Good and Bad Examples

Jun 22, 2017 17:51 · 1452 words · 7 minute read requirements guide user story

What is Software Requirements Specification for?

Creating a business, product or a piece of software, is a complicated and long winded process that starts with clearly defining the end goal. Setting a clear target is one of the most crucial things you should do before getting down to the execution. Solid planning already ensures 50% of your future success, right from the get go. The software requirements specification, very often, is the developer’s bible, for guidance and direction.

Eventually, a requirements document is something that you compare reality with, the document where your expectations face the current state of your business and determine how many of them have already been done. However, it shouldn’t be a concrete plan. It should speak about “what” needs to be done rather than “how” you think it should be done. The methods you use to get to your goals is not as important as achieving them. There are seven characteristics given below that your software requirements sheet has to have in order to be complete.

User story - definitive

Zen of Python says “There should be one – and preferably only one – obvious way to do it”. You should also follow this rule when you’re creating your requirements. It is absolutely crucial to avoid any ambiguity and eliminate potential misinterpretations in the subsequent stages.

Good Bad
As a User, I want to sign up via email and password so that I can access my account. There has to be a way to authenticate.
It clearly states who can do what and why. It doesn’t cover many cases but at least it is definitive. Later you can think of expanding this description with other cases. It doesn’t provide much information. This is an implicit statement and could (and would) be treated not the way you want it. Take your time and express who can do what and why.

Scenarios - verifiable

Have you ever thought would would be an acceptance criteria for the requirements created? Ask yourself what would be a definition of done and specify it in your document. Think of a scenario that has to be passed in order to consider something as completed. Otherwise, how would you know that something is done? Having clear acceptance criteria and test scenario allow to implement the automated automation of verification on a later stages.

Good Bad
As Administrator, I want to download a CSV file with all users in a system via a web interface so that I can use it in marketing.

Given User has admin permissions
When User navigates to administrative panel
And User selects to download a CSV
Then CSV file with email, first name and last name gets downloaded
I want to download the list of all users in CSV or Excel.
Now, a developer can easily verify if he did the job or not. Think of pre-conditions (Given), action (When) and results (Then) as a pattern for your scenarios. It is an ambiguous requirement. Probably, you imply that you need admin permissions etc but it’s not obvious. Be clear and specific about the steps.

Acceptance criteria - explicit

Be explicit in your definitions and don’t rely on someone else’s common sense. Your specifications should be self-sufficient and should not implicate any additional features. If you think that the phone number format has to be +x (xxx) xxx-xx-xx, it does not necessarily mean that others will have the same assumption. If you think it is important, make sure you add it to your specification.

Good Bad
As a User, I want to sign up via email and password so that I can access my account

Acceptance criteria:
Scenario: Successful sign-up

Given User is on the signup page
When User enters an email
And User enters a password
And User submits a form
Then User receives an email with confirmation link.

1. Password shall not be less than six characters
2. An email and passwords fields are required
3. is not allowed to be registered
I want to have sign-up functionality from business domains only. Can we have an email confirmation too?
This kind of user stories declares user scenarios, exceptional situations, and how system a should react on them. It is important to think about all the edge cases and explicitly describe them. Doesn’t have to be a scenario for each case. A list of constraints will work This doesn’t provide any information about what should happen if those are blank. The description also has a question in it which makes it ambiguous whether or not to implement it

Atomic story - simple

BBeing a Python development company we appreciate Zen of Python statements. Thus, another statement is also true here - Simple is better than complex. Indeed, the easier the goal, the lesser the chances of getting it wrong. Split big tasks into smaller ones and carefully describe all of them. Small and straightforward user stories are easy to understand and thus, faster to implement. The estimation process is also much easier to do with smaller tasks.

Good Bad
As a User I want to send messages to support agent via contact form so that I can get help online

Scenario: User leaves a message through the help page

Scenario: User views tickets

And so on…
I want to build a support system with live chat, contact form, help and case management
This can be a part of a bigger help system that includes much more than just a contact form. But do one thing at a time. Contact form itself is already has a value by itself so why not to separate it? Imagine, how much cases there can be? Online chat support, phone support, 247, email support, help pages on your website etc. There are dozens or even hundred cases. Don’t overcomplicate it and keep it simple


Each request should be holistic, atomic and valuable by itself. It should bring something to your product or business. If it’s a part of a bigger system and relies on other components – fine, but it shouldn’t be something you can’t use without further development.

Good Bad
As a User I want to log in via Facebook

Scenario 1, Scenario 2, Scenario 3 etc
I want to store user’s Facebook ID in the database
This is good because it brings new feature to your product and doesn’t really requires any further developments. It has business value and expands your product. It doesn’t make much sense by itself. There is an assumption that other features will require that data so you should consider to make it as a part of other requirement that actually uses this Facebook ID


Before you create a task, check its feasibility, in principle. If you are not sure, set the task as explore whether this, this and that is possible. Do some research or let others do research beforehand. It will save you time and eventually define whether or not you can meet your business goals. Validate, then act.

Business and product oriented

The last option aims to set goals for your business. Try not to think of exact implementation; leave it for later and maybe even to others who can handle the specifics. Although, you should be confident that your goals are technically possible, do not limit them to a particular technology. You are building a product at this stage, so think about the product as one solid unit. If you are certain about a particular technology, create a separate document or section. If not, the developers will probably know what to offer, to do justice to your idea.

Good Bad
As a User I want to view a chart that shows a percentage of time spent on particular websites.

Scenario 1, Scenario 2 etc.
As a User I want to view a pie chart that is built using highcharts or D3.js.
There is plenty of room for creativeness. You mentioned a chart but it can be pie or linear chart. UI designer will help you with that. The only thing you know is that chart will be valuable for your end users. Mixing technical details with business requirements often leads to a narrowing the angle of view. You may miss better opportunities that other technologies offer. Your focus is lost to less important things


Having clear software requirement specifications is as important as good implementation. This is why paying so much attention to those details makes you look more professional and makes your life easier. In our company, we use user stories to define goals and set tasks. This allows us to focus on the most important aspects of the product and avoid wastage. Please, see the continuation of this topic in the guide to how to create a good user story.

We will notify you about new posts every few weeks