How to write a good software requirements specification (SRS)?

Creating a good software requirements specification (SRS) significantly increases the chances that the outcome of a project will meet the needs of the client. However, many people find it quite difficult to create a specification that is understandable and clear to the dev team. So, what is necessary to write a good IT project specification?

IT project specification – what is it?

A software requirements specification is a key documentation element of every software-related project. It describes the basic expectations, i.e., the objectives of the project, and the features of the software which are going to be created. An SRS is a document through which the contractor gets to know the client’s expectations. It is especially important because the client usually expects that after analyzing it, the provider will present at least a rough estimate of the project. This is the beginning of the future product, which can be an application, a system, or a website. The specification should include the key assumptions of the project to create the expected solution. The document shouldn’t have gaps in the functional expectations and should leave as little space as possible for the interpretation of the analyst or developer. It is worth mentioning that although the specification resembles an official instruction created for the contractor, its main purpose is not to describe the future solution, but it should be focused on the needs of the client and the goals of the system. A software requirements specification is a key documentation element of every software-related project. It describes the basic expectations, i.e., the objectives of the project, and the features of the software which are going to be created. An SRS is a document through which the contractor gets to know the client’s expectations. It is especially important because the client usually expects that after analyzing it, the provider will present at least a rough estimate of the project. This is the beginning of the future product, which can be an application, a system, or a website. The specification should include the key assumptions of the project to create the expected solution. The document shouldn’t have gaps in the functional expectations and should leave as little space as possible for the interpretation of the analyst or developer. It is worth mentioning that although the specification resembles an official instruction created for the contractor, its main purpose is not to describe the future solution, but it should be focused on the needs of the client and the goals of the system.

First and foremost a need, not necessarily a solution

Many people who intend to write functional specifications already have some ideas for a targeted solution. It is quite natural that such ideas significantly affect the final document. However, it is not uncommon for a client to describe in the SRS a product which he wants to receive while forgetting about the main purpose of the document, i.e., describing the need for a certain solution. This is a source of potential problems. It may turn out that the final product is as described in the document, but it doesn’t meet the needs for which it was created. Although a specification can include some suggestions of particular solutions, it should never leave the main need unexplained. It is quite likely that an experienced software development company will prepare a very good and even sometimes better solution concept. After all, an IT systems implementation company can be expected not only to have a range of experience from previous projects but also to have extensive knowledge of available technical solutions that the customer may not know about. Of course, such a provider should also bring out the basic need, which is sometimes buried under the description of solutions invented by the client. Highlighting the needs will make communication much easier and probably speed up the development of the final solution.

How to create a good software requirements specification?

Language

An SRS should include a list of requirements that determine the functionalities of the product. It is worth remembering that the professional terminology you are using as a client may not be understood by the contractor. That’s why it is also important to clarify non-obvious and sometimes even misleading terms.

If you don’t have programming skills, it is better not to try to use technical language. Incomplete knowledge of a topic can lead to serious misunderstandings. It is best to use natural language, but you have to remember about getting rid of industry slang and explaining important concepts and jargon phrases. Also, it is worth including a glossary. As a result, you will avoid confusion. A glossary of technical terms is useful for the reader. Often, there is also a need to create some terms for the system that have not yet been named in the customer's business, but whose naming is necessary for the design of the application. In this case, it is best for both parties to discuss this matter. From our experience, we know that such terms quickly permeate the everyday language in the company, so it’s good to take a moment for their proper selection and unambiguity. And here comes another risk. When developing systems, it is often necessary to change the current terminology used in the client’s company. Two departments in a company may use the same name for completely different things. Then it is best to separate these names and replace them with appropriate synonyms. For example, the analysis department may use the term "report" to describe a report for the management board, e.g. charts, quarterly profit report, etc. Therefore, we put a reports module in the system. The operations department also talks about reports all the time, but here this term means something a little different. For them, reports are surveys done daily by employees on the status of the number of people and available equipment in the city. The operations department wants their report modules, too. It's best to talk to representatives from both departments and get them to change the naming – there won't be room for that level of ambiguity in one system. The analysis department can use the report module, and it is best to create a survey module for the operations department and use the term ‘survey’ in the system rather than ‘report’ for the work done by the operations department.

A coherent design vision

Sometimes a system specification is co-developed by many people, often with different expectations. It often happens that specifications prepared by numerous teams are just a cluster of "wish lists" of different people, which may lead to the duplication of some requirements or, what is worse, to contradictory requirements. Therefore, it is extremely important for the final form of the document to be evaluated and edited by one person whose task is to define one coherent vision of the goal which is to be achieved by the system. This is the role of the analyst, who must gather all the requirements and edit them. It is not enough just to write down the needs of all the parties. The analyst must propose a solution that will meet the requirements of all or almost all the parties. Sometimes analysts must explain that not all the requirements are worth implementing. A classic example here is trying to put sophisticated validation into the system. The big advantage of applications over "paper" and Excel is that we can prohibit users from entering incorrect data. Features like validating dates and numbers are the basic requirements that can easily be implemented in the system. But business requirements such as a maximum number of products in a package or the minimal time of delivery should be considered with caution. Sometimes some customers require more products than the company limits allow, and others may live nearby warehouses so the delivery time is below minimal.

Document size

One of the most common "sins" of clients is a specification that is too long. To be understandable, it should be short and focus on the main problems and processes. Of course, it should still cover all the functional requirements, but it is better if it does not go into too much detail. A popular approach is, for example, to describe requirements as use cases, i.e. specific scenarios of interaction between the user and the system. We guarantee that every analyst prefers to ask about missing details than to wade through dozens or hundreds of pages of descriptions of irrelevant details.

Technology constraints in the specification

Except for some cases, the specification should not impose certain solution technologies. Sticking to a given solution instead of putting needs first creates unnecessary limitations, often unfavorable for the customer. If nothing determines the choice of a particular technology, it is better to leave this decision to an experienced provider who will take into account not only the specification but also current trends in the IT market which can affect the possibility of software development in a few years. On the other hand, if technological limitations are justified, it is wise to explain them. For example, a good reason for limiting to a particular technology is having other systems written in it.

The purpose and business context of the project

Apart from defining the problem to solve, it is worth including the business aspect in the specification. Many customers forget how important the broad context is. Who will use the system, in what circumstances, and what benefits is the system to bring?  Often these questions about the context are the first ones we ask our customers. The answer usually clarifies any ambiguities in the specification.

System limitations

When creating an application specification, it is common to discuss a lot of features and functions that will not be implemented in the app. Various ideas are considered at analytical meetings and some of them turn out impossible to implement, redundant, inconsistent with the final design, or simply too expensive. It is natural not to pay too much attention to the rejected features when an analysis is created. Over time people forget what was rejected and why. But ideas come back after some time and it is often difficult to read from the specification whether they were left out intentionally or just as a result of negligence. That’s why it is worth writing down such arrangements. The specification, when describing specific missing functionalities, should contain information about the possible solutions outside the system. For example, it may specify that the interface will not have a “Print” button, and the user can print the page through the browser’s print function.

Completeness of requirements

In an analyst's job, one of the most important things is to gather all the aspects of customer requirements. This requires close cooperation between the parties. Preparing a complete specification is a serious challenge. “Complete” means that the finished system will have all the features needed to work efficiently in the system. It may be a problem if some of the operations, employees, cases, products, or variations are omitted. Let’s look at another example. The company has one office and employs office workers only. The first response to the analyst’s question “do employees work in shifts in the company?” is “No, our employees are supposed to be in the office from Monday to Friday, 9 to 5”. However, it turns out that the employees of security teamwork on shifts. An experienced analyst will ask more domain-related questions and go deeper into the specifics of the client’s work. That will help to identify most of the edge cases, but cooperation from both sides is needed. Good modeling of all of the company’s activities and processes which will be transferred to the system can be a long and complex process.

Summary

This article can be summarized in a few words: specifications should include all important information. However, this is not an easy task. Therefore, if there is a need, we can perform an analysis ourselves and prepare a specification for you. You can avoid others’ mistakes by reading about why IT projects are delayed.