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 the common requirements 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 tell us these aspects, they often wrap them in the statements which hide the core information. Below we present examples of statements that need to be first analyzed to get the underlying requirements out of it.

Requirements Leading to Functions

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

It is very common to see such a form of requirements when the new system is based on some 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 works at the moment.

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 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 which 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 some data, there will certainly be some user interface. However, the user interface itself will not save the data, so it must always be complemented with a function that will do 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 remark it does not say how the inactive items shall be marked - 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 includes 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 despite they all could be put in a flat list, some requirements make more sense to be placed under some higher-level requirement, which gives them 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 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 it's 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 the form, which is unambiguous, clear, and understandable 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 this does not present the trap. The trap is that although it might seem that all requirements are related to the function which saves the product, it is not like this. Experienced analyst quickly realizes that the patterns must be managed somewhere and includes the 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 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 is in the ambiguous word "to support", which doesn't give any context whatsoever. Again, such a requirement is very common for the early stages of the requirements elicitation. However, during the requirements analysis, it should be refined to explicitly say what impacts it is going to have and what other requirements it is going to generate:

Purchase Product

  • Select Products
    • ...
  • Select Delivery Method
  • Pay for Products
    • User shall be able to select 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 using the "shall support". Without defining a relevant function, it is not clear where this constraint shall 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 upon 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 the partial changes may change the way they will work. The trap is, these impacts may generate additional requirements that nobody has realized at the beginning, which are not easy to identify and which may cause troubles 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. Analyst discovered that the parcel status is already being tracked, but there are about 20 of them, and most of them are internal information, so they are not suitable for being presented to the customers. In cooperation with the business people, the analyst managed to define just 5 "customer states" to be shown on the portal and the implementation has started. But a few days later, things started 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 the information to be able to respond to customers' 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 that is currently under development would like to include the state of the parcel in the application as well, which implies exporting the state 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 just 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 the legacy application or following a legacy business process, stakeholders are too tight with the old solutions that they struggle to think out of the box to design new, better solutions. The only advice here is you need to become an expert in the area you're trying to improve, be a partner to them and help them open their eyes and provoke creativity. This means coming up with new ideas, asking open questions, discovering imperfections of the old solution, and seeing behind the corner.

Stakeholders Dictate Technical Solution or Implementation Details

A very common characteristic of many stakeholders is they cannot separate their needs from solutions to these needs. Besides, they often intentionally propose the concrete solution in good faith 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 the crucial questions:

  • Have all possible solution alternatives been evaluated?
  • Is this solution really the best from 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 which 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 the 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 by no means cannot 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 the Gama would be a waste of time, assuming that the 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 everybody. 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 “they think they know”. The reason why they mentioned the AdvertParner system is just to ensure that advertisers will see the credited bonus under their profile - this is actually out of the box since all transactions are visible there. Then they are mentioning ReportCube. They have no idea this system just downloads the reports and shows them to the users. The report is generated in the other 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."