Effective Analysis and Documentation

Examples and Traps

In this chapter, we are going to show various requirement examples so that when you spot any of them, you will know how to handle them. We will also illustrate common requirement traps, which may puzzle you in the sense that some requirements might not be what they seem to be at first sight.

Typical Requirements

When analyzing a solution, we need to find out what the system shall do, what processes it shall support, what data it shall store, or how the user interface shall look. Although stakeholders try to explain these aspects, they often wrap them in statements that hide the core information. Below, we present examples of statements that need to be analyzed first to extract the underlying requirements.

Requirements Leading to Functions

Users are created in Active Directory and synchronized to the Portal every hour

It is very common to see this form of requirement when a new system is based on a legacy system. Stakeholders describe how things work at the moment, but requirements should be written in a form that emphasizes what should be implemented, not how it currently works.

So the requirement could be rewritten to something like this:

  • Users of the portal shall be imported from Active Directory (future function)
  • Users of the portal shall be synchronized with Active Directory every hour (future function)

Requirements for Storing Data

System shall store following data about each bicycle: manufacturer serial number, color

The requirement clearly states what data should be stored, but the data will not appear in the system by itself, so the analyst needs to do a cross-check to ensure that there is a way to create the bicycle in the system. In practice, there must be a function that imports the data or a screen that enables the user to create a bike.

Requirements Leading to User Interface or Some Output

User shall be able to enter following attributes about each bike: manufacturer, serial number, color

If the user must be able to enter data, there will certainly be a user interface for it. However, the user interface itself will not save the data, so it must always be complemented with a function that does it.

System shall display all bicycles the company offers or has ever offered. Items which are not provided anymore shall be marked and displayed after those which are still in offer.

This is basically the same case as the previous one. We include it to note that it does not say how the inactive items shall be marked—whether by color, icon, etc. This is a design decision, not a customer requirement, so it is absolutely fine not to include it until the final design is known.

All printing outputs related to purchasing a product shall include a note stating that our website is just a intermediator and all questions and claims shall be directed at the actual seller

The requirement specifies what information a particular system output should include, but it contains the ambiguous word "all". Instead, it should specify which concrete outputs shall be modified:

  • An Offer shall include a note stating that our website is just an intermediator and all questions and claims shall be directed at the actual seller
  • A Purchase Contract shall include a note stating that our website is just an intermediator and all questions and claims shall be directed at the actual seller

Sub-Requirements

As already stated in this chapter, requirements are never a flat list of textual statements. Requirements form hierarchies, and although they could all be put into a flat list, some requirements make more sense when placed under a higher-level requirement that provides them with context.

Customer shall be able to login to the customer zone only within 2 years after purchasing a bike

It is a valid requirement, but since it specifies a parent function and adds details to it, it would make sense to place it under the parent requirement:

Log In

  • System shall block logging in for a particular user name for 30 seconds after 5 unsuccessful attempts
  • Customer shall be able to login to the customer zone only for 2 years after purchasing a bike
    • After this period, the system shall display an error message

After submitting an order, an e-mail shall be sent to the customer summarizing the order

Similar to the previous one. The requirement is valid on its own, but it makes much more sense when put into context:

Create Order

  • Select products
    • ...
  • Submit order
    • After submitting an order, an e-mail shall be sent to the customer summarizing the order

Traps and Challenges

Non-Analyzed Requirements

Non-analyzed requirements are requirements that are stored exactly as they were stated by the stakeholders. Eliciting requirements is only the first step, which must be followed by requirements analysis to transform them into a form that is unambiguous, clear, and understandable, which is even more important.

A product page title shall be generated automatically when the product is saved. The title shall be generated according to a predefined pattern. Each product category shall have own pattern.

These are actually three requirements, but that is not where the trap lies. The trap is that although it might seem that all requirements are related to the function that saves the product, they are not. An experienced analyst quickly realizes that the patterns must be managed somewhere and includes a requirement for this as well:

Creating Product

  • ...
  • A product page title shall be generated automatically when the product is saved
    • The title shall be generated according to a predefined pattern

Settings

  • ...
  • User shall be able to set a different page title pattern for each product category

System shall support these payment gateways: PayGo and DynamicPay

At first sight, the requirements are clear. The sponsor wants to enable customers to pay using either of these payment gateways. The problem lies in the ambiguous word "to support", which doesn't provide any context whatsoever. Again, such a requirement is very common in the early stages of requirements elicitation. However, during requirements analysis, it should be refined to explicitly state what impacts it will have and what other requirements it will generate:

Purchase Product

  • Select Products
    • ...
  • Select Delivery Method
  • Pay for Products
    • User shall be able to select the PayGo or DynamicPay gateway

Administration

  • Payment Gateways Administration
    • Manage PayGo credentials
    • Manage DynamicPay credentials

The system shall support listing up to 5 pictures per product

This is very similar to the previous one, as it puzzles analysts with the phrase "shall support". Without defining a relevant function, it is not clear where this constraint should be applied. Assuming it describes how many photos must be possible to add to a product when creating it, the requirements may be rewritten like this:

Create Product

  • It must be possible to attach product photos
    • It must be possible to attach up to 5 photos

Requirements Hidden in Impacts

Requirements come from stakeholders who have an interest or a gain in the successful completion of a project. But on most projects, there is also a group of people who will not be directly impacted by the change in general, or who will not use the final solution, yet partial changes may alter the way they work. The trap is that these impacts may generate additional requirements that nobody realized at the beginning. These are not easy to identify and can cause trouble as they are often discovered later in the project.

For example, a transportation company wants to enable customers to see the status of their parcels online. An analyst discovered that the parcel status is already being tracked, but there are about 20 of them, and most are internal information, so they are not suitable for being presented to customers. In cooperation with the business stakeholders, the analyst managed to define just 5 "customer states" to be shown on the portal, and the implementation started. But a few days later, things began to complicate. First, a customer support manager points out that if new information is to be shown to customers, customer support also needs to see this information to be able to respond to customer inquiries. They need to see the status in their system, which therefore needs to be updated as well. Next, the business intelligence team mentions they have multiple reports showing the number of parcels in each state, and they want your project team to create the same report for the new customer states. After several days, a product manager of a new mobile app currently under development would like to include the parcel status in the application as well, which implies exporting the status to the data warehouse.

As you can see, what was just a simple requirement for the customer portal evolved into a project with multiple teams changing 3 enterprise systems. The only reason behind the scope increase was focusing solely on the requirements and forgetting the impacts.

Other Traps

Stakeholders Struggle to Free Themselves From How Things Work at the Moment

Having worked for years with a legacy application or following a legacy business process, stakeholders are so tied to old solutions that they struggle to think out of the box to design new, better solutions. The only advice here is that you need to become an expert in the area you are trying to improve, be a partner to them, help them open their eyes, and provoke creativity. This means coming up with new ideas, asking open questions, discovering imperfections in the old solution, and seeing around the corner.

Stakeholders Dictate Technical Solution or Implementation Details

A very common characteristic of many stakeholders is that they cannot separate their needs from solutions to those needs. Besides, they often intentionally propose a concrete solution in good faith that it will streamline the analyst's work. Unfortunately, it usually has quite the opposite effect.

Example 1: For our high-value advertisers, we need to implement a web portal to provide them with more up to date information and let them feel more VIP

No matter how innocent this requirement may look, it must turn on a red light in the analyst’s head. A skilled analyst should realize that besides the business need (an opportunity to give advertisers more information), the statement also includes a solution (to implement a web portal). This is dangerous because the analyst has not been involved in the solution definition process and cannot answer crucial questions:

  • Have all possible solution alternatives been evaluated?
  • Is this solution really the best among the alternatives?
  • Will the suggested solution provide the best value for the price?

The suggested portal could really have been selected as the best possibility by evaluating a couple of other solutions. But it also might be just an idea that is not supported by any analysis. In the latter case, until the solution is confirmed as the best one, the analyst should work only with the business need, ignoring the solution part. In other words, only this part is relevant at this moment: "We want our high-value advertisers to have more up to date information and let them feel more VIP".

Example 2: The algorithm calculating customer rating must be updated in the system Gama according to the new legislation.

One of the most frequent traps is based on the stakeholders' confidence that they know best how systems should work. What they think is: "Gama has always been the system calculating the rating, and because the new legislation forces us to change the algorithm, Gama needs to be updated accordingly." Unfortunately, stakeholders see the IT architecture just from the user’s perspective and they can by no means foresee all impacts. They have no idea that the customer rating was newly implemented centrally and all systems will be calling this system to get the rating. This change will become effective in Q4/2018, which is also the date when the legislation will come into effect. Therefore, updating the local algorithm in Gama would be a waste of time, assuming that Gama will be connected to the central system in the same release.

Example 3: We want to reward our high-value advertisers by giving them $1000 credit in the system AdvertPartner. We also want the ReportCube system to put a note about topping up the credit to our R-12 report.

A great example of how stakeholders can gracefully mix everything together and confuse everyone. The business goal is clear: to give high-value advertisers a one-time bonus. The rest are just ideas based on their level of knowledge and on the fact that “they think they know”. The reason why they mentioned the AdvertPartner system is just to ensure that advertisers will see the credited bonus under their profile—this is actually available out of the box since all transactions are visible there. Then they mention ReportCube. They have no idea this system just downloads reports and shows them to users. The report is generated in another system, which just confused the analyst a bit more. The above requirement should be rewritten to something like this: "We want to reward our high-value advertisers by giving them a one-time $1000 credit. Advertisers shall be able to see this credit in their transactions list in the AdvertPartner portal. The bonus shall also be visible in the R-12 report."