What Is A Specification?
The expressions such as "I've written a spec." or "We are going to implement the software according to some spec," have acquired an almost folk status among developers. However, our personal experience is such that the majority of junior developers do not know what that "specification" is. This text sets as its objective to offer a brief introduction into the problematic as well as to clarify the basic concepts and to serve as a stepping-stone for a further study.
An obstacle that one can encounter is that a specification on its own does not signify anything in particular unless one decides to define its object.
Cambridge Dictionary defines specification as
a detailed description of how something should be done, made, etc.
Therefore, when creating a software so called "specification" can be diametrically different things, for example:
- Software Requirements Specification
- is a detailed description of what the final software product is going to solve or what the final software product is going to do. However, a description of how the software achieves the specified behavior is not present there.
- Software Solution Specification
- is a detailed description of the problem solution.
- Input Format Specification
- is an exact detailed description of the format in which information is recorded.
In this text we are going to deal exclusively with Software Requirements Specification. This specification deals with the question: ‘What is the final software product going to solve?’ in detail. The central part of this document is a list of particular requirements. However, it neither deals with the software design nor with the software implementation. At the same time, the concept "specification" denotes the document itself in which this specification is recorded.
The Central Part Of The Software Requirements Specification
As it was mentioned previously, a central part of Software Requirements Specification is a list of requirements. Every requirement must be fulfilled so that it can be bought by a customer. In order to plan software development activities, it is crucial to:
- check the actual status of particular fulfillment of requirements
- allocate requirements to particular team members
- assign each requirement to a source code that is aimed at realizing the requirement and so on
Therefore, it is inevitable to sensibly number and organize particular requirements.
Now, let's show an example. These requirements are related to an online reservation system for buying airline tickets and eloquently expresses some important characteristics of those requirements.
- V-01 Online system allows end users to search for flights.
- V-02 End-user has to fill in these mandatory input fields: departure (airport), arrival (airport), departure date.
- V-03 End-user can choose between one-way ticket and return ticket.
- V-04 In case of a return ticket, end-user also has to fill in the input field: 'arrival date' that becomes mandatory.
- V-05 Arrival date must not forgo a departure date. If that happens, the system will notify the user.
- V-06 In case of a return ticket, 'departure (airport)' input field equals to 'arrival (airport)' input field.
- V-07 All dates and times are entered into the Gregorian calendar at the local departure or the arrival time.
- V-08 Local departure time must be a date in present, not in the past. Otherwise, this online reservation system displays an error.
- V-09 After successful 'search-flights activity', a list of flights matching end-user criteria is displayed to end-user; ordered by descending departure dates.
- V-10 If no flight matches the end-user criteria, then online reservation system displays warning: 'No flight matches your criteria. Please change them.'
- V-11 Searching appropriate flights is implemented using GDS XYZ.
- V-12 If the connection to GDS is interrupted or is not established for other reasons, online reservation system tries to re-establish the connection once again (3 times at maximum).
- V-13 If the flight search was not successful because of a GDS unavailability or an error, then the reservation system displays a warning with the following meaning: 'An external supplier error occurred. Please, repeat your search after a few minutes. If the error persists, please contact our support.'
- V-14 Response time for a one-way ticket search cannot exceed 5 seconds.
- V-15 Online reservation system must be available at least 95% time of the year.
Try To Avoid Implementation Details As Well As Design Details
Please notice, that we have striven to stick to an abstraction when formulating particular requirements. For example, in V-02 requirement, we do not put effort into coming up with some creative way of defining dates, e.g. by selection from a calendar. We leave those out undefined. A decision on how to make it, belongs to design and implementation. Since software developers and designers know best what is feasible and what is not feasible. Moreover, a designer’s virtuosity is often orders of magnitude greater than a virtuosity of customers. As far as this area is concerned, designers and developers are the most capable ones making decisions.
Now, please let’s have a look at V-08 once again. The formulation of this requirement just informs that system should respond to an incorrect end-user’s input, but it does not tell us how exactly the system will perform its reaction. For example, the system may either display an alert window containing an error message of a particular formulation or it may play some sounds. If our customer insists on a particular system’s behavior, then we can do nothing but to take it as his or her requirement. However, implementation details should not be included in Requirements specification document, since they do not belong there.
In general, requirements priority often helps in project management issues. This is especially true with software projects! Software projects’ deadlines are usually tight and there is no time for designing, implementing and testing all the requirements. This is why it is crucial to agree on, what system’s features should be delivered: in the 1st, 2nd, 3rd version of the system. Moreover, there is one more benefit of this strategy. If our project is in a time delay, then we have a prerequisite knowledge about what features can be left out!
Functional And Non-Functional Requirements
Taking into account the content of requirements, they can be classified into two groups:
- Functional requirements
- describe what system should do. Typical examples of functional requirements are those included in our list (V-01 to V-13).
- Non-functional requirements
- describe those attributes/characteristics of the system that are visible for end-user or customers. Typical examples are requirements described in V-14, V-15. One of them describes the availability of the system while another one describes response time that a system has.
When To Split Requirement Into Multiple Ones And When To Aggregate Multiple Existing Requirements Into A New Requirement?
There is no simple answer to this. It makes no sense to split the V-02 requirement into two requirements: "User must specify departure" and "User must enter destination". On the other hand, by aggregating requirements V-01 to V-04, we create a requirement that contains too much information and this might cause unnecessary misunderstanding. There is no need to pose philosophical questions such as ‘When is the requirement sufficiently atomic?’. Let’s take a pragmatic stance and use a common sense. We should ask ourselves these questions:
- How can we benefit from the splitting?
- After splitting aggregation, is there anything clearer or more understandable?
- Do the splitted requirements make sense separately?
- Does it make sense to implement some of the requirements right now and some of them in the next version of the system?
How Do I Know Whether The Requirements Are Captured Well?
Like most things, gathering and documenting requirements is an iterative process. That means, you have to validate whether requirements are complete, unambiguous, contradictory, verifiable, over and over again by asking the following questions:
- Is my list of requirements complete?
- You should be acquainted with each system requirement. There is no need to be informed about how each requirement should be implemented, but you need to know how the system should behave externally (from end-users’ point of view). If I ask questions such as 'What exactly should system do after clicking on this button?', 'When should the notification emails be sent?' while reading a specification, then the specification is not complete! Specification should be such that the developers are able to design and implement system and there is no need to ask customers 'And how should this user-system interaction look like?' over and over again.
- Is each one of my requirements unambiguous?
- In specification, each of our statements must be unambiguous. It is incorrect to write something like this into our specification: ‘After clicking on the X-button, the previously mentioned email notification should be sent.’
The programmers might misinterpret that sending emails is an optional feature of the system and thus decide not to implement it into current version of the system. So we have to create statements that are unambiguous.
The ambiguity of the requirements also has a major impact on the smoothness/fluency of the whole software process. If programmers do not know exactly what the system is supposed to do, they generate permanently/regularly additional questions towards the creator of the requirements specification and this causes a considerable delay.
- Aren't our requirements contradictory?
- None of the requirements must oppose each other . If that occurs, then it is clear that at least one of the couple is wrong. And now, which one is the right one? Moreover, what if there are also other contradictory couples?
- Are all of the requirements verifiable?
- One of the most important things is to satisfy customers’ requirements. This is why it must be absolutely clear whether each requirement is fulfilled or not. One of the consequences is that a metric or criterion (saying whether the requirement is fulfilled or not) must exist for each requirement. For instance, here is an example of an incorrect requirement that cannot be sufficely verified: ‘System must process the specified list of products very quickly.’ To compare, this is an example of a verifiable requirement: ‘System must process the specified list with 1000 products up to 4 seconds.
We must consider all of the above mentioned questions when we try to formulate a good requirement. For each creator of requirements, each requirement formulation is clear and meaningful, because the creator knows the exact meaning. However, the point is to achieve the requirements that also have all the above mentioned attributes from the programmers’ point of view. Despite it is always really difficult, here is a procedure that should help you: look at each of your requirements unbiased and try to interpret each word of any requirement statement separately and then reconstruct the meaning of each statement from the separated interpretations.
Requirements Specification Document
As with any decent document, the requirements specification document should look perfectly from both aspects: content and form. This document should not contain a list of requirements. The readability of such a document would be very low, especially at the 1st reading. Therefore, It is beneficial, if the document contains at least these sections:
- that describes the main purpose of the software system and briefly describes its scope. Moreover, this part also contains the list of terms used in the document.
- System Context
- briefly describes the interaction of the system with all other systems that are integrated with them. The emphasis is not being put on the technical aspects of the communications (such as protocols, communication mechanisms, etc.) but on the main responsibilities of all of the systems. This is why this section clearly defines what the system should do and, especially, what the system should not do. So this section indirectly defines boundaries of all of these systems.
- Requirements Specification
- This is the most important part of the document, containing the list of requirements.
Standard IEEE 830 is the one supposed to answer the question: ‘What should the requirements specification contain?’. If he or she had not written at least one such specification, the standard could hardly be useful to him or her. From my personal experience, I can confirm that this is not the one of the easiest readings.
In this section, we are going to provide you with some inspirations. But do not take them as a standard of flawless specifications. Each work contains some shortcomings. Read them carefully and with an open mind.
More about software requirements specification can be found here:/p>
- Karl E. Wiegers. Software Requirements. It discusses software requirements broadly from many viewpoints. Topics such as requirements gathering, change management of requirements, and so on can be found here. It provides readers with some valuable information.
- IEEE 830 This is a IEEE standard, not a book. Therefore, do not expect any detailed explanations.
- Search, the keywords are "software requirements specification".