How to write a good software requirements specification (SRS)?
Grzegorz Papaj, 1 July 2019
Creating a good software requirements specification (SRS) significantly increases the chance that a result of the IT project will meet the needs of a client. However, many people find it quite difficult to create a specification which can be understandable and clear to the team of developers involved in the project. So how to write a good IT project specification?
IT project specification – what is it?
Software requirements specification is a very important element of documentation of every project 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. The importance of the specification of requirements is increased by the fact that the customer usually expects that after analyzing it, the provider will present at least a rough estimate of the project. This is the beginning of a future product, which can be any application, system, website, etc. The specification should include the key assumptions of an IT project and should allow to create the expected solution. The document shouldn’t include gaps in the functional expectations, leaving as little space as possible for the interpretation of the analyst or programmer. It is worth to mention that, although specification resembles the official instruction created for the contractor, in the first place it shouldn’t describe the future solution, but it should be focused on the needs of the clients and the goals of the system.
Write down your needs, not solutions
Many people who intend to write functional specification 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 losing the basis of the document, i.e. the need for which the system should provide a solution. This is a source of potential problems. It may turns out that the finial product is as described in the document, but it doesn’t meet the need for which it was created. That’s why it is worth emphasizing that although any specification can include some propositions of particular solutions, should never leave the basic need unexplained. It is likely, that an experienced programming service provider will prepare very good and even sometimes better solution concept than any of the proposed. After all, you may expect that the company dealing with the implementation of IT systems has not only a huge experience from previous projects, but also has extensive knowledge in the field of the available technical solutions that the customer may have never heard 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. But exposing the needs will make the communication much easier and probably speed up the final solution.
How to create a good programming project specification?
The IT project specification should include requirements which determinate the functionalities of the ordered product. It is worth remembering that as a client you can use nomenclature and professional terminology unintelligible for the contractor. That’s why it is also important to clarify non-obvious and sometimes even misleading terms.
At the same time, you have to remember that if you don’t have programming skills it is better not to try to use the technical language. The incomplete knowledge of the topic can lead to serious misunderstandings. It is the best to use the natural language, but you have to remember about getting rid of industry slang and explaining important concepts and jargon phrases. It is worth including a glossary of industry terms from client’s activity in the specification document. It will allow to avoid subsequent misunderstandings. The basic glossary of technical terms is a very useful thing for a reader, who can easier understand the domain related terms. It is also quite common that a need of creation of some new terms appears. Usually it relates to some processes or activities which are regularly conducted but have never been named, but whose naming is useful or even necessary in the process of designing of the system. In such case, it is the best for both sides to discuss the nomenclature. From our experience such terms very quickly move to the everyday language in the company, so it’s good to spend a little time for finding good ones. And here comes another risk. You often have to change the current nomenclature used in your company when a system is deployed. It may be that way, for example when two departments in the company use the same term for describing entirely different things. Then it’s the best to separate these terms and replace them with appropriate synonyms. Let’s look at example. The analysis department can use a term “report” for describing a report for the management board, e.g. charts, quarterly comparative report etc. Therefore the report module is placed in the system. The facility department also talks about reports all the time, but they have something else in mind. For them reports are surveys carried out daily by employees. The facility department also wants to have its own module of reports. It is the best to talk to representatives of both departments and make them to change the nomenclature – in one system there will not be place for this kind of ambiguity. The analysis department can use a module of reports, and for the operational department it is the best to create a module of surveys and use in the system term survey, rather than the report for the work done by the operational department. It’s just a simple example – the nomenclature problems can be much more serious in the real live companies, especially the big ones.
Coherent vision of needs
Sometimes the specification of the system is co-created by many people, not uncommonly with different expectations. It often happens that the specifications implemented by multi-person teams are a mere cluster of “wish lists” of different people. Because of that some requirements can duplicate or, what is much worse, contradict each other. That’s why it is important for the final version of document to be approved and edited by single person who is responsible for defining the one coherent version of the goals that the system has to achieve. Here the work of an analyst can be valuable. The analyst has to collect all the requirements and compile them. It is not enough to write down needs from everyone. Analyst has to propose a solution which will meet the requirements of all (or almost all) parties. Sometimes his/her role is also to explain to interested people that not all requirements should be accomplished by means of the system. The attempt to place a sophisticated validation into the system is a classic example. The big advantage of a computer application over paper or Excel solutions is that you can prohibit users from entering incorrect data. Some data like dates, numbers, etc. can be easily validated. That’s are the basic requirements which can be easily implemented in the system. But the business requirements such as: maximum number of products in a package or minimal time of delivery should be approached with caution. Especially if they didn’t function in the company before the system. It can happen that for some recipients the company may agree to extend the maximal number of products. And for those who reside in the same city the delivery can be much below the official minimum delivery time. The system should not limit the business decisions.
Size of the document
One of the most common “sins” of the specification creators is to write a document of excessive length. The understandable SRS should be short and focused on the main problems/processes. Of course, it should still cover the entire functional requirements, but it is the best not to go into too many details. The popular approach is for example describing requirements as use cases, i.e. specific scenarios of interaction between user and the system, which quite often multiply by may times some basic information. Be sure that every analyst prefer to ask about missing details than to read through dozens or hundreds of pages of irrelevant details descriptions.
Technical limitations in the specification
Besides certain specific cases, the specification of needs shouldn’t impose specific solution technologies. Despite the fact that it is specifying a solution not describing a problem (what was mentioned above), the unnecessary restrictions can also quite often be excessive for the client. 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 of the system but also current trends in the IT market which can affect e.g. the possibility of software development in a few years. On the other hand, if technological limitations are well justified, they must be presented without not ignoring the reasons of their occurrence. For example a good reasons for limiting to a particular technology is having other systems written in it.
The purpose and business context of the project
Besides determining the problem which has to be solved by the system, it is worth including the business aspect in the specification. Many clients forget about the importance of the broadly defined context: who will use the system, under what circumstances, what benefits the system is supposed to provide, etc. Often the question about the context is the first that we ask our clients. The answer usually explains most of the uncertainty in the specification.
When a SRS is created, 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 or inconsistent with the final design or simply too expensive. It is natural not to pay too much attention to the rejected features when an analytical document is created. It’s lifetime is from several months to several years. Overtime the memory of what was rejected (and why) dissolves. Some of those ideas come back after some time and it is often difficult to read from the specification whether the lack of them was an intention of a creator or just a result of a negligence. That’s why it is worth writing down such arrangements. The specification, when describing specific missing functionalities, may contains information about the possible solutions outside the system. Fort 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
At analyst’s work, one of the most important thing is to gather all the aspects of customer requirements. This requires cooperation between both parties: client and provider. To create complete specification of requirements is a serious challenge. “Complete” means here that the finished system will the client to transfer the full range of the designed process to the system. It may be a problem if some of the operation, employees, cases, products, variations, etc. are omitted. Let’s use an example again. The company is placed in one location and employs office workers only. The first response for analyst question “does employees work in shifts in company?” is “No, our employees are supposed to be in the office from Monday to Friday, 9 to 5”. After that, it turns out that the employees of security work 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 the 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.
The whole of the above elaboration could be summarized in a few words: specifications should be written substantive, taking all important information into account and not to long. However, we realize that is not an easy task. Therefore, if there is a need, we can perform an analysis ourselves and prepare specification for our you. Other mistakes you can avoid are described in the article: Where do delays in IT projects come from?