Software Requirements Specification — Part I
By: Giuseppe Terrasi
Tags: Software Requirements, Software Development, Software Analysis, Process Analysis, Requirements

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.