How to Write Software Requirements Specifications: Best Practices and SRS Tools

Reading time:

8

minutes

How can a client and provider reach a mutual understanding on the concept of the product? It’s not easy when they speak different languages. A customer defines a product at a high concept level, focusing on the external system behavior: what it will do and how end-users will work with it. Meanwhile, developers think of the product in terms of its internal characteristics. That’s why a Business Analyst steps in to translate a customer’s needs into requirements, and further transform them into tasks for developers. This is initially done by composing software requirements specifications.

Poorly specified requirements inevitably lead to some functionality not being included in the application. Every assumption should be clearly communicated rather than just implied. For instance, NASA’s Mars Climate Orbiter mission failed due to incompatible units of measure. Nobody specified beforehand that the attitude-control system and navigation software should both use the same metric or imperial units. For some, it went without saying, others didn’t find it as obvious. This is a common problem that keeps happening even to the best experts if not prevented.

Inaccurate requirements gathering is one of the top causes for project failure, Source: PMI’s Pulse of the Profession

In this article, we are focusing on the role of software requirements specifications in the development process and offer practices and techniques to create a SRS documentation your team will thank you for. Also check our video on software planning and documentation to get the idea.

Software documentation, explained in less than 11 minutes

What are Software Requirements Specifications

Software Requirements Specifications (SRSs) comprise a technical document that describes future software functions and capabilities, its characteristics, design, and implementation constraints for the development team.

SRS is at the bottom of the software requirements hierarchy, which goes like this:

Top tier – the high-level business requirements (BRs) dictating the goal behind the product,

Middle tier – user requirements (URs) that picture the end-users and their needs, and

Bottom tier – SRSs that specify the product’s functionality in tech terms.

Solid arrows show how requirement types (ovals) are sorted into the documents (rectangles). While dotted arrows show which requirement type is the origin of or influences another one, Source: Software Requirements by Karl Wiegers Joy Beatty

SRS structure is modified depending on the project but it always includes functional and non-functional requirements.

Functional requirements include features and functions that allow the system to perform as intended. They are composed of:

• if/then behaviors,
• description of the system’s workflow,
• logic behind data handling, and
• data inputs and corresponding outputs.

Functional requirements describe the system’s behavior in response to the input, Source: QRA Team

Non-functional (NFR) requirements, aka quality attributes, describe the desired system properties and constraints it must respect. Although there are hundreds of NFRs, the most common types are

• performance and scalability;
• portability and compatibility;
• reliability, availability, maintainability;
• security;
• localization; and
• usability.

For more specifics, you can read our article about NFR types and recommendations on documenting them.

Best practices for documenting and managing the SRS

The SRS is written in a single document communicating functional and non-functional requirements. It usually comes in a form of user stories or use cases. User stories are more suitable when describing the system itself, while use cases describe how a user interacts with this system.

Sample use cases and corresponding user stories, Source:Software Requirements by Karl Wiegers Joy Beatty

So, when writing use cases and user stories that compose your SRS, we advise sticking to the following practices.

Visualize. Enriching your SRS with visuals like diagrams, schemes, and models contributes to a better understanding of the processes. Visuals are irreplaceable when it comes to showcasing the main functions and their interoperability. For visuals, a nice technique is mind mapping as it organizes ideas (features and scenarios) generated during brainstorming and shows connections between them. There is no need to draw a complex mind map with detailed explanations for all features. It’s better to focus on critical concepts and then explain them in the SRS.

Visual representation of knowledge, concepts or ideas related to technical drawing, Source: GoGeometry

Avoid ambiguity. The SRS should be clear and not cause endless discussions or second thoughts. Remember, it’s not the developer’s task to fill in the blanks. If they get “creative,” it will end badly. Ambiguous language means fuzzy words like synonyms and subject adverbs (e.g. reasonably, generally, approximately). Terms combined with a slash (e.g. Delivery/Fulfillment Team) can also cause confusion. Some interpret slash as “or,” while others as “and.” Refrain from using tricky boundary values as well as double and triple negatives. A formal peer review is a good way to spot ambiguities. This way each participant can compare his understanding of requirements to someone else’s while a BA can make the necessary corrections.

Be customer-oriented. After you’ve done field research and conducted user interviews, you should have a portrait of your end user. Use this info and think of the operations an end-user is going to perform with the software, taking into account every little nuance . Then put it into the SRS document. Remember that developers don’t read your mind. They should implement no more and no less than what they were told. It’s not their job to take into account every possible scenario that can happen with the software – it’s a BA’s task and it should be documented in the SRS.

Include only what serves. There are a lot of different SRS templates, so sometimes a BA can be confused as to what information to include in the doc. In this case, it’s necessary to embrace the mindset of a critical thinker. Always keep in mind why this or that requirement must be implemented, question yourself how it will help the product reach the final goal right now because that’s what matters most in terms of priority.

Prioritize. Each requirement comes with a time dimension that helps prioritize it. Near-term SRSs describing the core functionality get high priority, midterms come with medium priority, and although hypothetical requirements are low priority, they are still necessary to get a whole picture.

Keep SRS flexible. Requirements must be flexible. BAs watch how the system works, get the feedback, access the outcome and if it’s not satisfactory – modify the requirement.

Ensure traceability. Each requirement gets an ID so that it can be easily tracked in the documentation. Reading the SRS, the dev team needs more context so it’s particularly important to crosslink the existing project documents with them. However, mind that your hyperlinks can break if the document folder hierarchy changes. That’s why a BA maintains a requirements traceability matrix. That’s basically a table that assembles a set of links that connect each requirement to the design and code elements that implement it and the tests that verify it.

Requirements traceability matrix for online shopping system, Source: Richard Lai

Save the history of changes. It can help avoid any misunderstandings. The team can trace each requirement to its original, see who made each change, when it was made, and the reason for it.

Make a glossary. Don’t forget to clarify the terms you’re using in the SRS. You can link some of them to the outside resources and explain those you’ve come up with yourself.

SRS software and templates

An SRS template provides a convenient reminder of what kinds of knowledge to explore. Every software development organization should adopt one or more standard SRS templates for its projects. There are various templates available depending on the project class. Here’s an example of an SRS template that works well for many types of projects.

A template for a software requirements specification, Source: Software Requirements by Karl Wiegers Joy Beatty

You also can use templates with visual emphasis to structure the information and aid in understanding it.

Though many BAs go with easily available tools like Microsoft Word and Google Docs, you may prefer using a requirements management software if your budget allows and you have time constraints. These tools make it easier to manage requirements – to track, test, analyze, visualize, and communicate to stakeholders.

Jira. Although Jira is primarily a product management tool, it also includes requirements management. Mostly used by Agile teams, Jira helps configure your requirements, facilitates test case traceability process, and allows for collaboration with sharing, watching, and commenting features.

Perforce Helix RM. A stand-alone module in Perforce’s Application Lifecycle Management suite, Helix RM is a useful tool for large, distributed teams. Its key features are requirements traceability, graphical tools, scalability, real-time collaboration features, impact analysis tools, and test case management, file history graphs, and even a time-lapse tool to visualize an item’s progress over time. Helix RM integrates well with Jira, various Microsoft products, Slack, Eclipse, GitHub, Go2Group, Rational DOORS, and OpsHub. The tool has quite a steep learning curve, so it’s accompanied by video tutorials, training, and a knowledge base.

Pearls. Once you’ve defined your use cases, actors, conditions, and flows, Pearls allows you to generate a requirements specification document with a single click. The tool has strong team collaboration features like comments and notifications about member activity, features for defining project goals, and managing stakeholders.

Reqchecker. It’s a simple tool for checking requirements coverage. Often used as an added level of assurance, Reqchecker’s traceability analysis makes sure requirements and tests are covered. Importing Word, pdf, Excel, PowerPoint, or XML files into Reqchecker, you can turn them into requirements.

SRS within the Software Development Lifecycle

Software requirements specifications are the starting point, where devs get their tasks, QA engineers understand how to make test cases, and technical writers start to create user manuals.

Working on the SRS, a BA maintains cooperation with the client to get the approval of the interface design and clarify any other controversial issues on the way. Describing some low-level technical details like data migration, a BA can consult a solution architect. Also, BAs actively work with domain experts who know how the system is going to be used and can give valuable advice on the requirements.

Let’s see how SRSs differ depending on the development lifecycle.

Waterfall. Although the waterfall development style doesn’t suggest a high pace, it’s the best choice for less experienced teams who won’t manage to pick up Agile or even Scrum speed. Waterfall allocates more time for writing SRSs. That’s perfect for business domains that need detailed requirements that aren’t likely to change any time soon and can be formed as a solid document.

Agile. This approach means a Business Analyst iteratively (usually every second or fourth week) gathers feedback from the customer and makes modifications to the SRS doc. This way, the software is developed module by module. So, once developers finish one module, a BA performs acceptance testing to check whether it meets the requirements.

Scrum. In Scrum, projects are built at high velocity, and tasks are added to Jira right away. This approach works for a skilled team that doesn’t need a BA to explain every little thing to them. Instead of a BA, here a product owner is focused on this one long-term project.