Why and How We Create Software Requirements Specifications

Imagine that you have started a project with an IT outsourcing company. How can you make sure that your software partner has understood your wishes correctly and will implement them exactly the way you want? The answer is: create a software requirements specification. In this article, we'll show you how this document can save your project and give you step-by-step instructions on how to create it.

When starting a project with an IT outsourcing company, a business owner is sometimes confused about why so much documentation is needed. From the outside, the work of a Business Analyst may look like a formality that delays the development phase. Nevertheless, each well-elaborated document saves the project from mistakes, delays, and financial losses. Below are the documents needed to ensure the success of a product.

Classic documentation: a Vision and Scope Document and a System Requirements Specification

The weaponry of a successful software development project should include the following documents: Vision and Scope Document, System Requirements Specification, Backlog, and User Story Mapping. All of them are created and agreed upon with the customer prior to the development stage.

A Vision and Scope Document — the product from a business perspective

Ideally, the work on a project begins with a document that answers the questions of what kind of program is being developed and why. Together with the customer, a Business Analyst forms the product image and describes what goals the business will achieve with the help of this software. In other words, a Vision and Scope Document - an artifact that is obtained as a result of the work of a Business Analyst with a customer (or customer representatives) at the stage of the discovery phase - is being created.

The Vision and Scope Document contains a set of business requirements (or business needs), high-level descriptions of system functionality, project priorities, a list of stakeholders, and other information. The Business Analyst develops the Vision and Scope Document so that all project participants have a high-level understanding of what the product is being built for.

Along with that, the Vision and Scope Document contains information about the “pains” of the business and its abilities to create a product. If we had described the problems of passengers in this document before the creation of Uber, for instance, we could have indicated that there was a lack of vehicles and people wanted to order cheaper cars faster. These are the problems that were solved with the corresponding application.

What is the benefit of a Vision and Scope Document for a customer? It helps in formulating clear criteria for the project's success and effectiveness. Thanks to this 10-page document, specialists have a quick understanding of what they will be developing and why. The Vision and Scope Document makes it easier for managers to convince investors of the product value.

A Vision and Scope Document looks as follows.

A System Requirements Specification — a product guide

A System Requirements Specification is somewhat of a “set of laws” that describes in detail the software functionality and what capabilities it provides to users.

The System Requirements Specification is the basis of the work of all specialists: a Project Manager, developers, and testers. Guided by this document, the PM knows when each particular task must be accomplished. Based on this specification, programmers write code, and QA specialists test software.

You can try to start a project without any specification, but the team won’t progress much further, as specialists don’t know what the system is supposed to do and how. The System Requirements Specification answers all these questions.

How can the customer benefit from the System Requirements Specification?

If there is no specification, the customer asks to do one thing, but the team may get this request wrong, so the resulting product will not be the one expected. Rewriting the program will take several times more money. With a specification, both parties are less likely to misunderstand one another, and the customer reinsures themselves against unexpected expenses.

The specification makes it easier to calculate the budget and compare the cost of the same project from different IT service providers.

The System Requirements Specification also reduces costs in the sense that programmers don’t have to, so to say, extort the requirements from the customer. The cost of a Business Analyst's time is lower than that of a developer. The Analyst translates the customer's language into the technical language of developers and clearly describes what is to be done in the system.

A System Requirements Specification looks as follows:

Vision and Scope Document vs. System Requirements Specification

Both documents are equally important for projects with a classic development methodology, where the “written work" comes first, and then the product is created. They complement each other so that a quality software product is built in the end.

First and foremost, the Business Analyst forms the vision of the product, high-level requirements for it, and general business rules (for example, based on legislation). The Vision and Scope Document aims to explain what the product is being created for and what it will look like, but it’s not a guide for building the system. Then, based on this document, the Business Analyst creates a System Requirements Specification to clearly describe the system in terms of functionality and performance.

In order to understand the difference, let’s imagine an educational platform. The Vision and Scope Document describes the stakeholders (principals, the government, teachers, students, etc.). The System Requirements Specification doesn’t specify the stakeholders but assigns roles to them. For example: “As a teacher, I can add a video to the video section” and so on. Therefore, one document won’t work without the other - both are important for organizing processes on a project.

Time required to create classic documentation

Writing classic documentation is a crucial stage - the quality of the product, the speed of development, and the success of the project as a whole depend on it. If requirements are poorly defined and structured, the system won’t perform as expected. This may entail unforeseen situations during a release.

For example, NASA's Mars Climate Orbiter mission failed due to incompatible units of measurement - the System Requirements Specification did not specify that attitude and navigation systems must use the same metric data.

Creating a Vision and Scope Document usually takes 2-4 weeks. To draw up a System Requirements Specification, 1-3 months are required in typical cases (sometimes longer). What tasks does the Business Analyst solve during this time?

1. Plans the work with the specification.

As Dwight David Eisenhower, the 34th president of the United States, said:

“In preparing for battle I have always found that plans are useless, but planning is indispensable."

Planning is essential in any endeavor. When you want to hang a painting on the wall, you choose which tool to make a hole with (drill, hammer, etc.). The Business Analyst, guided by the customer requirements and project conditions, determines how and what specification to create. With templates in hand, the Business Analyst proceeds to the next stage.

2. Develops and approves the specification.

In order to compose the System Requirements Specification, the Business Analyst communicates with the customer or their representatives to determine what functions are important to implement in the product. Then, this specialist studies, analyzes, and documents the information collected.

It is recommended for a Business Analyst to check the finished document with another specialist before showing it to the stakeholders. In our opinion, the best candidate to help with checking is a tester. Testers are scrupulous people who are used to looking for nuances and inaccuracies.

After the requirements are verified and validated, i.e. after the check of how correct and consistent they are, the Business Analyst sends them to the customer for approval. If everything is fine, the development team starts working on the requirements; if not, the Business Analyst makes changes to the document. When the specification is ready, developers, testers, and other specialists involved in the project come into play.

3. Manages and maintains the specification to ensure it’s up to date.

When changes occur in the project, the Business Analyst makes changes to the specification. They are recorded in the change history so that they can be easily tracked.

It should be added that, for especially complex and sizeable projects, the creation of specifications can take up to one year. In this case, all the stages of creating specifications happen in parallel, and the customer receives the requirements for approval in portions.

Custom documentation

Backlog

When it comes to projects carried out according to the Agile methodology, the specification takes on a non-standard form called Product Backlog. The Product Backlog is a collection of all the tasks to be performed and all the information about the product. This document includes not only descriptions of the system's functionality but also questionnaires, templates, presentations, and so on.

User Stories or use cases with sets of acceptance criteria make up 80-90% of a Backlog. The rest is additional information about the product in a rule-free format, which requires revision (draft).

A Backlog looks as follows:

In classic methodologies, the software specification is used, as the customer has a clear vision of the system - from the beginning to the end of the project. If there is no such understanding and the customer is guided by the let's-start-and-take-it-from-there principle, a Backlog is used. As new features are discussed, this list is complemented with new tasks that go in the next sprint.

User Stories (aka tasks) are prioritized. For example, the task of introducing credit card payments is more important than the task of introducing Apple Watch payments. This prioritization is demonstrated in the Backlog - User Stories are decomposed as much as possible so that the team can start working on each of them at any time.

The Backlog replaces specifications in Agile projects and is used in all methodologies. In classic cases, a Backlog is formed from the System Requirements Specification, tasks from which are entered into product management tools (for example, Jira). These tasks are performed to implement the specifications.

The Backlog structure

The Backlog makes it possible to structure the vision of the future product for correct transfer to development, task setting, and their subsequent estimation.

A Backlog is divided into large tasks - Epics - that are impossible to finish in one sprint. Epics, in turn, are divided into smaller tasks - User Stories. For example, Enter the System is an Epic, while Enter the System by Login and Password, Enter the System by Phone Number, and Enter the System with Your Fingerprint are User Stories. Thanks to this fractionation, the Business Analyst understands what has been done within a single Epic or sprint.

The Backlog includes questionnaires, API documentation - any tasks that are needed for the product's success. Something must always be happening in there, even if the product is in a stable phase. The Backlog dies only when the product ceases to exist.

What is the value of a Backlog for the customer? This document is an alternative to the software specification for Agile projects. It has the same value for the customer as the classic System Requirements Specification. The customer sees that the team correctly understood their requirements and is fulfilling them according to the documentation. For the sake of argument, if the manager has asked for an apartment building, they won’t receive a three-story house in the end, as all the functionality is agreed upon in advance.

User Story Mapping

A User Story Mapping is a visual representation of all user steps.

Imagine that there is a task to create a product or a large module of it. A Business Analyst walks with the customer or the end user through all their steps - from the first contact with the system to the final goal. For example, a user begins with logging in, then selects a product, adds it to the cart, checks out, pays, and so on. These are big steps.

Then come Epics - big steps, broken into small ones. For example, the Select a Product step is divided into Epics like List of Products, Add to Cart, Possibility to View the Product, etc. Then smaller steps (User Stories) are described: Filtering the List, Sorting the List, and so on.

Thus, step by step, a high-level description of how the system will look in terms of functionality and user requirements is obtained. Then, this map is converted into a Backlog.

A User Story Mapping looks as follows:

The USM makes it easier to prioritize User Stories and track whether all tasks were completed in the sprint. It is being created in parallel with the Vision and Scope Document to form a clear picture of the future system. With the USM, it is more convenient to define the boundaries of a minimum viable product that will solve simple problems. For example, a list of products without sorting, filtering, or searching is the most simple functionality that allows a user to get a finished result (view the product).

How does the USM benefit the customer? This document provides a well-defined visual image of what the system will look like. Thanks to the tabular format, the Business Analyst will not miss important steps in the map because they will be discussed during the creation process. When all the steps are taken into account, there is no need to modify the system, which will significantly reduce the customer's costs.

Conclusion

A working product is not yet a success. It gains value when achieving the specific business goals that had been set before it was created. Properly developed project documentation reflects business goals and is understandable to the development team. It helps the team to act according to the planned course and saves time and money in achieving goals. As a result, we release a product that is valuable to users.

A Business Analyst doesn’t write project documentation all alone but rather involves everyone in the process of creating it - from end users and the customer to the development team. Kirill Zabavsky, a Business Analyst at Anderse, comments:

“Great things can’t be done single-handedly. Only in the course of numerous disputes, multiple discussions, and reflection will you be able to consider all the details and describe exactly the product that will satisfy the wishes of end users and achieve the business goals set by the customer.”

It is impossible to create a great product without a good plan. If you have an idea for a project, our Business Analysts will help you identify and draw up the necessary documentation for its successful implementation.