Software Engineering

Towards a Good Requirement Specification Document

  • Software
  • Software Engineering
  • Requirements Engineering
  • Requirements Elicitation



We have to be honest, writing requirements specification documents (req docs) is not fun. Writing good req docs involves a lot of working hours. You have to write about the desired features, ensure there are no contradictions between them, and ensure they are unambiguously and clearly expressed. In many cases, it is necessary to create diagrams and tables to complement explanations. Moreover, the tasks become more difficult as the number of features and complexity of the software to-be-developed increases.

If writing a req doc is hard, reading them may be even harder. In many cases, a req doc could be hundreds of pages long and fully comprehending a document of such a size may take lots of hours. Since req docs tend to be many pages long, it is common for developers not to read them and, even worse, not update them as the requirements of the software evolve.

So now you may be wondering, if writing req docs is a hard task and if developers do not typically take the time to read and update them, then why spend time creating such a document? Why is writing req docs important?

I consider req docs to be an asset as necessary as other assets like source code and unit tests. My goal with this article is to illustrate why creating req docs is essential, the role it plays in the development process, and good practices when creating them.

Importance of Req Docs

Explaining the role that a req doc plays throughout the development process is the the best way of appreciating its importance.

The req doc is created early in the development process. It is a result of close collaboration between the customer and the supplier. Later in the development process, programmers and software architects use the req doc as input for designing and programming the system. Finally, at the end of the development process, both the supplier and customer use the req doc as the baseline for verifying that all requirements have been met. Since real-world project does not typically work in a linear manner and developers do not finish one phase before starting the next one, it is common for requirements to be added, deleted, or changed during the design and programming phase [1].

The req doc is typically part of the contract between the customer and the supplier. Therefore, if things go wrong, the req doc may end up in court as evidence of what was agreed.

In essence, the req doc can be used as:

  1. Input for architects and programmers when designing and building the system.
  2. A tool for verifying the final product complies with the agreed requirements.
  3. A legal document that demonstrates what was agreed to be implemented.

Moreover, for market-oriented software, the req doc can be used as training material for onboarding new team members.

Consequences of not having a Req Doc

Many factors could cause a project to fail and not performing requirements engineering activities is one of those factors. Req docs are essentials for defining the level of quality needed in the system and it facilitates decision making and negotiation with the customer. From a management point of view, it is the basis for tracking progress and determining when the project has been completed. It serves as a basis for testing the final product and verifying the product meets the requirements. Without a document that specifies the goals of the project, the features it needs to contain, and the quality level to be achieved, it is not possible to determine when a project is ready and complete [2].

If no req doc is written and only a selected group of people in the company are familiar with the requirements and needs for a given client, then how do people access requirements-related information whenever those individuals leave the company or move to another project? Req docs can reduce the risk of data loss and communication gap. If senior team members leave the company or move to another project, other (or new) team members can access and read the req doc.

Good Practices when Creating Req Docs

Req docs. should be treated as a living asset. Just like source code, it should evolve with the software. Updating req doc at the end of the development process is more laborious and more time consuming than evolving in parallel to the source code.

Since most, if not all, requirements are specified in plain English, it is a misconception to think that anyone who knows how to read and write is capable of correctly specifying requirements. Proper requirements specification requires training, and in this section, I present 5 tips to get started.

  1. Express "What," Ask "Why," & Avoid "How": Req docs should contain the functional and non-functional requirements; i.e., the "what." It should also clearly provide a rationale for each requirement; i.e., the "why" but it should not contain any information regarding "how." The reason is that specifying "how" is part of the design phase and the system should not be limited to any implementation details while gathering requirements.

  2. Complete and Correct: As a whole, the req doc should specify all relevant requirements that are necessary for satisfying the needs of the user. The key words are "all" and "relevant." If relevant requirements are missing, the customer may not be satisfied with the final product. Additionally, the requirements need to be correct. Failing to correctly identify the problem, goals, and needs of the customer may also result on unsatisfied customers. It is essential for analysts to successfully identify the correct set requirements that are most relevant to the customer [3].

  3. Customer Oriented: Too often developers or highly technical individuals are responsible for creating the req docs. As a result, they use technical jargon that is not understandable to other stakeholders. Therefore, it is essential that whoever writes the req doc uses a language that key stakeholder can easily understand regardless of their technical background [3].

  4. Lack of Ambiguity: Requirements should be unambiguous and clear. Failing to do so, could result in misunderstandings that could lead to creating the incorrect product [3].

  5. Feasibility:There is no point in creating a req doc containing requirements that cannot be implemented. Therefore, it is crucial for analysts to ensure that the established requirements can be developed with the existing hardware and software available. Besides technology availability, it is critical to ensure that the requirements can be implemented within the budget and schedule limitations.

Conclusion

A requirement specification document is an asset that not many companies take as serious as other assets like source code or test. However, why bother to create the best architecture and internal software quality, if the software you are building does not satisfy the needs of your customers? You can spend all your resources ensuring your source code is up-to-date, but if no one uses it, it is useless.

Requirements specification documents allow companies to make decisions, to negotiate with the customer, to validate the customer's needs, to verify the final product, and as training material. Failing to put the effort in creating and maintaining the requirement specification document could result in consequences that could affect your company negatively. Finally, keep in mind that anyone can write requirements. But not everyone can write good and useful requirements. Keep in mind the best practices and ensure the requirements in your document are usable not only by you but also by your team.

If you enjoyed this article, please recommend and share. Don't forget to subscribe and follow me on Twitter to stay up-to-date with my latest posts. See you in the next one.

References

[1] Software Requirements: Styles and Techniques, chapter 1 by Soren Lauesen
[2] The Top Risks of Requirements Engineering by Brian Lawrence, Karl Wiegers, and Christof Ebert
[3] Specifying Good Requirements by Donald Firesmith

● ● ●

How would you rate this article?