Software Requirements Specification — Part I
The survival guide
I’ve been working in the software development industry for ten years and leading a team of ten developers for five.
Should I choose one thing, the uttermost important, among all the ones I learned during this time I’d undoubtedly say: Software requirements specification.
Why is it so important?
Because EVERYTHING regarding the success of the project depends on it. The requirements document you’ll write after the software analysis will be the only (or one of the very few) document that both you and the end customer will rely on when something goes wrong or doubts arise. And both of these are going to happen, surely.
What is a requirement?
Following the definition adopted by Wiegers Karl E. And Beatty Joy in the book Software requirements (Developer Best Practices) we could quote:
Requirements are a specification of what should be implemented. They are descriptions of how the system should behave, or of a system property or attribute. They may be a constraint on the development process of the system.
Software bugs are the rule when implementing custom applications, it’s been estimated that the US alone spends $30 billion annually in rework due to requirements errors (1).
So, now that you know how crucial is to write good software requirements let’s dive into practice and see some tips and experts’ recommendations.
1. Template: the one asset you need
Having a template ready will save you and your team plenty of time and this isn’t the only advantage. A template will also provide a valid resource to list everything that is necessary to include in the technical document, reducing the risk to forget something important.
Even if you already have an official template, my advice is to always look online for inspiration. Online you can find some templates to adapt to your needs, so that you can create your own or integrating an existing one. Otherwise you can read a book on the topic, for example, the before-mentioned Software requirements (Developer Best Practices) (Wiegers Karl E. And Beatty Joy) which is considered a staple in its field.
It is advisable to revise your template often, removing any old reference and integrating it with new notions and paragraphs.
2. Diagrams and schemes: use, don’t abuse
Diagrams are often much clearer than word descriptions. There are many types of schemes you can use to represent processes and information, each one can be useful in different ways, depending on what it’s used for.
Here is a list of the most commons.
- ER
The entity-relationship model is used to define relations between elements, for example objects or entities. It is commonly adopted for describing database schemas, since it makes it easier to define the relationships between the various objects.
- BPMN
The Object Management Group [https://www.omg.org/bpmn/ ] defines it as follows: The Business Process Model and Notation (BPMN) specification provides a graphical notation for specifying business processes in a Business Process Diagram. Its goal is to support Business Process Modeling by providing a standard notation that is comprehensible to business users yet represents complex process semantics for technical users.
BPMN is great for processes since it uses a proprietary set of icons to describe actions and events covering a broad range of cases.
- UML
The Unified Modeling Language is perhaps the best known in the field of software engineering. It is best suited for representing the design of a system. Most of the time it is used for defining software classes, properties and relationships.
- Flowchart
The flowchart is widely welcomed for any general representation since it’s simple, quick to design and equally valuable for several purposes.
A final word on diagrams and similar. Always keep present that any scheme simply represents the imperfect interpretation and transposition of what a human being has understood about requirements, never rely on formal methods as they were the ultimate truth.
In a 1999 article Robert Glass (2) analyzed the studies upon the improvement of productivity and quality obtained using seven different development technologies. Some of the methods presented advantages, but these start emerging only after a progressive decrease in quality and productivity due to learning and training.
Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away. — Antoine de Saint-Exupéry
3. Requirements elicitation: stakeholders and approaches
In an article (3) written for the PMI (Project Management Institute) we read
“Understanding the attributes, interrelationships, interfaces among and between project advocates and opponents, assists us in strategically planning our project. Herein lies a large portion of our project risk and viability, and ultimately the support that we must effectively obtain and retain.” and again
“It becomes obvious that an understanding of stakeholders’ needs and expectations is crucial to success”
Stakeholders are your main source of information, anything that will be part of the requirements writing will be proposed, reviewed and approved by them.
Not involving all the necessary participants in the software analysis will inevitably lead to project failure.
Assuring everyone’s participation, though, is often complex, because the necessary actors could be multiple, therefore inviting all of them to every meeting and activity could result in a time-money investment the customer can’t afford.
Just bear in mind that, more than often, end users are the only ones who know how the system shall work and what is needed to make it functional.
There are different approaches to requirements elicitation, the following are the most common.
- Reverse engineering
If the project scope is to renovate an old application or system, the analysis will often involve a reverse engineering activity.
Reverse engineering, in this case, is the activity to analyze the software in order to gather the requirements needed for its (re)development.
This scenario could present several advantages and disadvantages.
First, having something that has already been used in production will demand comparisons; therefore any feature will be compared with the one implemented in the other app. This attitude will generate the risk of disappointment for the final users who, being used to the old product, will presume (read pretend) that the same UI, UX and functions will be applied to the new one.
So your job, applying reverse engineering, will consist of understanding the old system while improving it at the same time. This activity is incredibly complicated and is almost impossible to perform without the help of who knows and uses the application frequently. Probably you ignore all the internal processes and methodologies of the company where the system is being used, so let the crucial stakeholders help you and clearly communicate the need to involve them to the top management from the beginning.
On the other hand, there are advantages to this situation. Already having an active application to use as a reference will avoid the necessity to build the requirements from the ground up, resolving several vital doubts that would have been raised during the analysis. Take advantage of this, but be careful with the risk of misunderstanding.
- Observation
Another approach frequently used is observation, which consists of, precisely, observing the end users doing their tasks and taking notes of processes, obstacles and needs.
As it is known, Observation should be done with a conscious effort to eliminate bias. Observations based on the analyst’s opinions are subjective and prone to misinterpretation since different people have different perceptions of reality. (4)
For this reason it’s important to be mindful when using this technique and ask users for help in understanding the activities and procedures involved.
- Interviews
The most common method for requirements gathering is the interview.
Interviews are easy to schedule and conduct and therefore preferred by the majority of the customers. If the scope is to assess general information about the system to build then a conference call is allowed. For more detailed sessions it is advisable to schedule a meeting in presence, in order to get the best possible outcome.
A good practice is to schedule enough time, but not too much, since the participants will lose focus and interests penalizing the final result. On average, four hours could be enough.
After every session, reorder your notes and send a report with all the specifications that were discussed, so that everything is put on paper while is clear in everyone’s mind.
This is the first part of a two-part article on software requirements gathering.
In the second half we’re going to discuss:
- Mockups: an image is worth a thousand words
- Constraints: be clear and provide the right information
- Versioning: keep track of every change
Stay tuned…
References
- [https://www.stickyminds.com/article/what-cost-requirement-error]
- Robert L. Glass, “The reality of software technology payoffs”, in Communications of the ACM, February 1999
- Smith, L. W. (2000). Stakeholder analysis: a pivotal practice of successful projects. Paper presented at Project Management Institute Annual Seminars & Symposium, Houston, TX. Newtown Square, PA: Project Management Institute.
- [https://www.businessanalystlearnings.com/ba-techniques/2013/5/16/using-the-observation-technique-for-requirements-elicitation]
