Good Practices

The following tips aim to help you become more effective in terms of requirements analysis and management.

1. Capture Requirements Rationale

Including rationale for all crucial statements is a core principle of the Effective Analysis, and it is even more important when it comes to requirements. Requirements rationale statement articulates why the requirement exists, any assumptions made, the results of related design studies, or any other related supporting information. While the requirement itself might be short and straightforward:

Product detail page shall include the number of customers who have bought the product in the last 3 days

...the rationale, on the other hand, could be longer as it includes any information needed to learn its background and motivation:

According to the last customer behavior survey, the other customers’ experience is more important for the buyer than the actual product description and price. Other shops have realized that people prefer to sort the products by the number of product purchases than by the price.

A clear rationale helps to spot requirements defects and shortcomings more easily, and it also reduces the risk of rework, as the reasoning behind the decision is fully documented.

2. Don't Mix Requirements Categories

Requirements represent high-level needs but also very specific requests, such as changing the color of the save button. There are several types of requirements, and analysts must learn to distinguish between them and document them accordingly. It is especially important to separate business goals from the software requirements so that the motivation is not mixed with the solution.

3. Don't Store Requirements in Documents

In this chapter, we presented how different types of requirements are usually organized in documents. However, the document in this context does not have to mean an electronic document such as Word or PDF. The analyst's goal is not to create a document but to coherently group all relevant information in the form which is easy to understand for the target audience. Instead of a document to read, take the specification as a container, which helps capture the relevant information in an organized way. As presented in the chapter dedicated to documenting requirements, there are many different ways of expressing what stakeholders need or want and most of them are not really suitable to be presented in a “document”. A complex process-oriented system, for example. Much of the documentation will consist of process models that are tough to manage in a Word document.

Analyst’s toolbox includes a wide range of software tools and techniques, and in most cases, it is not possible to include all possible outputs into a single document. For this reason, the goal should not be to create one universal document to include all the analyzed information. The more convenient way is to have an online "hub", which either includes the information or links to it. Covering all information in a document is a heritage from the old ”waterfall times”, when the specifications used to be created upfront and when the only tools were word processor and a basic diagramming tool. Nowadays, there are other possibilities available such as online collaboration tools, CASE tools, modeling tools, etc. and it is not necessary to produce clumsy jumbo documents.

Another issue with documents is duplicating information. When two documents are targeted to different audiences but need to include the same information, you have no other choice than to include the information in both. The solution is not to write documents but to generate them. Documents are no longer the source of information because they only present it and provide a view on the data stored in a database. This requires storing as much information as possible in a single repository and generating the information to documents ad hoc. It is then easy to create different documents serving different purposes to different audiences without the need to manually update all documents when requirements change:

The above example illustrates the basic idea. However, what seems to be straightforward for a few textual requirements could be quite challenging on a larger scale. For example, if the documentation is to contain models, tables, business rules, etc. We elaborate on this topic in detail in Part III.

4. Set Requirement Priority Using an Attribute

Not all requirements are equal, so they are usually assigned a priority. Some resources advise prioritizing requirements using keywords such as must, could, should, etc. (see MoSCoW method). For example:

System must validate the email address before sending the email (necessary)
System should validate the email address before sending the email (important)
System could validate the email address before sending the email (nice to have)

In practice, though, it is a much better idea to always use one keyword and stick with it. Although "shall" is generally accepted keyword for this purpose, we advise using "must" which is clear and works for most languages. Another issue is, this method works only for textual requirements, so a method to prioritize other requirements must be found anyway. Besides, the keywords tend to be misinterpreted by people, and because the keywords are ambiguous by nature, they transfer the ambiguity to the requirements too. The solution is simple. Just use a numeric range 1-5, and assign each requirement this value representing its importance. This approach is straightforward, works for all requirements, and allows you to easily sort and group requirements according to their priority.

5. Naming and Wording

Choosing a good pattern for naming textual requirements can greatly influence the readability of the requirements specifications. Calling a requirement "Calculation" makes it impossible to guess what the requirement actually means.
Software requirement is always something the system should do or something it should have, which is why the general form of "System shall..." became popular and is widely adopted. It is clear at first sight what we want from the system, be it a capability or characteristics. For example, "System shall display a warning when the limit of contacts is exceeded" or "System shall respond in no more than 500ms in 98% of cases" are clear requirements, defining a required function or technical characteristics. Therefore, this form is useful for defining the functional requirements of the systems. However, due to the popularity of this statement, a lot of people use it to describe all requirements, including user needs, which leads to creating clumsy expressions, such as "System shall enable the user to create new contact". Such requirements are better described from the user perspective rather than from the system perspective so they do not state what the system should do but instead what the user wants from the system - “User must be able to create new contact”.

There are several popular patterns which can be used when stating requirements from the user perspective:

As a <Role> I can <Capability>, so that <Receive Benefit> (User Story)
When <Situation> , I want to <Motivation> , so I can <Expected Outcome> (Job Story)
In order to <Receive Benefit> as a <Role>, I can <Goal/Desire>

However, do not fall into the trap and do not try to state all requirements using a single form. Each requirement is different, so no predefined pattern will work in all situations. The variety of requirements is quite wide, so not all requirements will always sound right with all patterns. Analysts need the freedom to express the user needs, and as long as the needs are clear, unambiguous, and easy to understand, it does not matter which of the following forms will be used:

ANTIPATTERN

Don't write requirements which do not clearly state who wants what and why such as:

REQ1: Sending information about the closed case to the bank through email

REQ2: Evaluating the customer request