How to Write a Software Requirements Specification Document: Best Practices
Imagine that you’ve found a reliable development team to develop your product. Now, it’s time to convey your product’s concept to the developers. But how can you convey the message so that both the client and the contractor understand each other? And so that, in the end, you get an expected, high-quality result? This can be tricky, as clients and developers often speak different languages. The customer usually defines the top-level product concept. Meanwhile, developers think of a product in terms of its intrinsic characteristics. That’s where the analysts come in. They study the client’s needs and formulate them in the form of clear requirements. These requirements will become the basis of tasks for the developers. This is done initially by writing a software requirements specification document.
Poorly defined requirements can result in a product that doesn’t solve the business problem you’re interested in. According to PMI’s Pulse of the Profession, the inaccurate collection of requirements is one of the main reasons for project failure:
In this article, we’ll explain what requirements are and how to create SRS documentation that helps the client and the development team stay on the same page and develop a successful product. Moreover, we’ll explore an example of software requirements specification from our practice.
What are Requirements in IT
Requirements describe the capabilities that the system should provide to the user. The content of the requirements may vary.
So, for example, to describe requirements, we often use approaches such as User Stories and Use Cases.
The functional requirements describe the behavior of the system. The non-functional requirements describe the characteristics of the system.
Types of Software Requirements
Requirements specification may vary depending on:
- stages of work on a project or task
- immersion degrees (business/user/system)
- the focus (functionality/properties of the system)
You can read more about the second and third type of requirements specifications here. Below, we will consider an approach to highlighting versions of requirements specifications for the same block of functionality depending on the stage of a project.
We divide versions of the SRS documentation into three groups:
- Concept. This version is for figuring out what the functionality should be. It will be supplemented and refined when requirements change. It should match stakeholders’ understanding of how the functional module should work.
- Dev. The development version. It can be supplemented and processed only upon agreement on all the requirements necessary for development.
- Prod. The documentation for the current version of the functional module in production. The version should only be updated in conjunction with actual system updates. The version history of the document must indicate the version of the module.
Stages of work on requirements typically look like this:
- collecting business requirements from the client
- preparing and agreeing on the vision with the client
- discussing with technical specialists
- allocating/coordinating with clients on the stages of implementation
- user interface development
- writing technical specifications for development
- coordination of technical specifications with the client/team
- writing user instructions
How to Write Requirements for Software
As we mentioned earlier, the content of requirements specifications depends on the specifics of the project, so there are no standards for writing them. But, some approaches serve as a guideline for our analysts. Let’s take a look at the key ones.
At Azoft, we characterize a requirements specification as a:
- result of the analytic process
- system snapshot
- solution to customer/team needs
The SRS document, produced as a result of the analytic process, must meet conditions such as:
- clarity and simplicity
Completeness means that there must be enough information to achieve the goal of its creation, namely:
- to agree on the scope of work at the Concept stage
- to start development at the Development stage
- to train the end-user at the Production stage
Consistency reflects the idea of the reader’s gradual immersion in context, the movement “from the general to the particular”:
- what is this?
- why does it exist?
- how does it work?
Clarity and simplicity mean that the specification document should be written in simple, plain language that readers will understand, taking into account their current level of immersion in the system.
The accessibility criterion draws attention to the fact that the project documentation should be stored in one place and any team member should have access to the documents as required for his/her role.
The requirements specification document as a snapshot of the system has some limitations:
- information presentation logic
The limitation of relevance means that the document tends to become outdated. The client and the team may abandon some functionality at the implementation stage. Additionally, the business goal and the way the requirements are implemented may change. Since the obsolescence of the document is inevitable, it’s important to indicate the date of its creation or the last update.
The logic for presenting information may differ from project to project. This is the imprint of the documentation requirements on the part of stakeholders. It’s important to note that the analyst also sets requirements for documents since he’s responsible for the process of collecting and analyzing the requirements.
The SRS document, as a solution to stakeholders’ needs, should:
- respond to stakeholder requests
Analysts work on requirement specifications considering the needs of the end reader. As a rule, to change the document is easier than to change the code, so the analyst needs to be flexible and tolerant of changes. Analysts strive to seek the balance between their expert view and stakeholders’ points of view.
- match their language and level of immersion in the system
Analysts also pay attention to the language of the documentation. They consider subject areas, as well as each team member’s level of immersion in the project. If necessary, they define specific terms in the glossary of the project. As a rule, business requirements should be described and agreed upon in User Story format, while technical implementation details may require mentioning lines of code, and other details.
Example of SRS Document
Let’s see how you can apply this approach to the analysis of requirements on the example of the development of the functional module in the iFarm project. We’ve been involved in the development of the iFarm system since 2019. The system automates various parts of the process of growing crops.
We chose Confluence to store the knowledge base for the project at the dawn of its development. So, by the time we started the Dashboard module revision from the point of view of documentation, the following conditions existed:
- Confluence Knowledge Base
- YouTrack task tracker
- 3 versions of the module description: Concept, Dev and Prod
We had to address the following issues:
- Where do we place and look for requirements?
- What are the current (recent) requirements?
- How do we manage changes in requirements?
To resolve these issues, we decided to:
- develop a procedure for working with tasks from YouTrack
- use an organizational system for managing changes in requirements
How we worked with tasks from YouTrack:
- Attached the corresponding pages describing the functional module from Confluence to the tasks from YouTrack during the analytics process.
- Linked feature pages in Confluence to related tasks from YouTrack.
To manage requirements, we developed the following change management system:
- Create a roadmap of a document describing the module/task/revision, namely:
- What should be done
- What module has been completed, what needs to be added and for whom
- Where to add
- Role-based access,
- How will it affect existing elements (a list of modules with a list of changes in each),
- How long will it take
- What is an approximate work plan, questions, etc.
- Separate the user story from the functionality that works without user intervention
- Combine questions from the analyst and the team in the comments, and record the answers in the body of the document with links to comments
- Generate action points with the date and the name of the person in charge in the body of the document
To clarify, in the context of the requirements specification documentation, we define the roadmap, as the structure and logic of the task description going from the general idea to the specifics (What? Why? How?).
By action point, we mean the key actions that need to be taken by team members as a result of discussing new functionality. As a rule, these actions are discussed at the meeting. This approach allows you to divide areas of responsibility and helps to move from the client’s task to specific actions for its implementation in the system.
Now, let’s see how we managed to apply this approach to preparing software specification requirements for the finalization of the functional module Dashboard.
Last year, we received a request from the client, which we formulated as a User Story:
As a user, I want to see an up-to-date dashboard for croppers as well as home modules.
Note: cropper is a growing module, a display cabinet with pots of fresh herbs that can be installed in restaurants and retail chains.
We described the current implementation of the module. It was focused on displaying key indicators such as temperature, humidity, watering, and light. We also formulated a list of improvements that could be made to the user interface and the system related to the integration processes.
Then, a meeting was held within the team. During the meeting, the analyst and the designer presented the improvements and the user interface. The engineers voiced their concerns about the limitations of the current implementation and asked questions that require additional clarification with the client. As a result of the meeting, we published a page in Confluence which became the starting point for the specification of requirements. In the image below, you can see several sections from the specification document.
Software requirements specifications for different projects are written based on the same principles. The challenge here is that there is no unified software requirements document sample, as each document has to be unique. From our experience in creating software requirements documents, we can highlight the following basic principles:
- Stakeholders can set their own requirements for the contents of the SRS document.
- The document is written for a specific reader, so it should correspond to his “language” and level of immersion in the system.
- The document covers issues from the general to the particular.
Depending on the purpose of writing and the level of immersion of the reader, the basic semantic blocks can be combined in different ways.
The approach described in the article is just a recommendation. Occasionally, we cannot adhere to the practices described above. Therefore, we perceive them as ideals and guidelines. Each task on the project and each project is unique and requires an individualized approach. If you have any questions or need assistance in making an SRS document, please contact us at firstname.lastname@example.org.