Software Requirements Specifications Good and Bad Examples

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

What is Software Requirements Specification for?

Creation of any business, products or software is a complicated process that starts with the end goal defining. Setting a clear target is one of the most crucial things you should do before acting. Planning is already 50% of future success. Software requirements specification document often is a developer’s bible in terms of guidance.

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 those has already been done. However, it is not your plan, it should say “what” has to be done instead of “how” would you do it. Goals achieving methods is not so vital comparing to their definition. Thus, there are seven characteristics described below that your software requirements sheet has to have in order to be completely good.

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 while creating your requirements. It is absolutely crucial to avoid any ambiguity and eliminate potential misinterpretation for the next stages of work.

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’s else common sense. Your specification should be self-sufficient and should not implicate any additional features. If you think that 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, just include that statement 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. @gmail.com 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

Being the 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 fewer chances to do it wrong. Split big tasks to a smaller ones and carefully describe all of them. Small and straightforward user stories are easy to understand thus faster to implement. Estimation process is also much easier to do with a 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

Self-Sufficient

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

Implementable

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 a research or let others do a research beforehand. It will save your time and eventually define whether you can meet your business goals at all. Validate, then act.

Business and product oriented

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

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

Summary

Having clear software requirements specification as important as a good implementation. This is why paying so much attention to those details makes you look like more professional and make the 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 waste.

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