Insights Blog Requirements: Into the Mind of the Author

White Paper

Requirements: Into the Mind of the Author

It seems well-accepted that it is cheaper to find defects earlier in the software development lifecycle than during dynamic testing or in live operation. I don’t need to include a graph of the cost escalation curve here; we’ve all seen it before. This rule can be applied to all walks of life – putting up a garden shed, building a house, buying a car, running a marathon – you name it and the adage “find problems early to save pain and aggravation later” always applies.

Kelvin Kam

Requirements reflect needs

Before we can start we have to know what we actually need. If the problem we have is “I need to store my lawnmower,” then we can decide on the right type of shed, its size, the interior height, the strength of the floor, where in the garden it is going to be located, and so on. Knowing what we need helps us design a solution to fit the problem. We might not even need a shed. The solution could be to keep the mower in the garage or buy a low-level store rather than a traditional garden shed. It is not just articulation of our problem but also due consideration of it that helps to ensure we don’t buy something we didn’t really need, pay more than we need to for features we’re not going to use, miss out on features that we do need, or buy or build an inappropriate solution.

So, where do we articulate our problem for IT projects? The answer is straightforward enough: in a requirements document or in a requirements management system. It might be sensible to define what is meant by requirements. In Writing Better Requirements, Alexander and Stevens say that a requirement is “a statement of need, something that some class of user or other stakeholder wants.” IEEE standards says it is “a condition or capability needed by a user to solve a problem or achieve an objective that must be met or possessed by a system or system component to satisfy a contract, standard, specification, or other formally-imposed document.” Although this is a much more expansive definition, both agree on a clear meaning: a requirement is something needed by a user or stakeholder. Requirements should not be design or solution – those will be documented elsewhere. Of course, we testers will want to test against the requirements.

Moreover, as testers, we rely on the requirements in order to create tests for scripted testing. If the requirements are wrong and we create tests to match them, they might pass system testing and maybe acceptance testing. But it may only be in live operation that the horrible truth dawns and the cry of “This isn’t what we need!” is heard. We might feel that we’ve done our job but the customer may not be happy with the result. For IT systems, if projects don’t articulate requirements clearly the costs can be very high indeed. Complaints from users, costly rework, damage to the reputation of software suppliers, contractual wrangles, financial penalties, or even abandonment of a system are all examples of what can happen.

Where requirements come from

The need, then, is for clear and correct requirements – but how do you get them? This is not the responsibility of testers (although we can contribute to it); it is the responsibility of the author of the requirements: the requirements engineer. There are different names for this role, such as business analyst and requirements analyst, but it comes down to much the same work. How does a requirement engineer set about getting clear, correct requirements? A suggested outline for approach is:

  1. Identify the stakeholders (those who have a need or an interest in the problem)
  2. Gather requirements from the stakeholders and other sources (e.g. documents)
  3. Structure the requirements
  4. Put the requirements in context
  5. Write the requirements
  6. Check and review the requirements

Identifying the stakeholders

Getting the whole picture is the key point here. There is a danger if an incomplete set of stakeholders is identified: vital aspects of the requirements will be omitted, only to rise up later and result in rework. Who are potential stakeholders? Examples of stakeholders could be users, sales teams, marketing department, the organization’s management, support technicians, regulators and legislators, external organizations such as clients and suppliers, and, of course, testers.

This is by no means an exhaustive list as it will depend on the context of the project, but it gives an idea of the wide variety of stakeholders that may need to be considered and consulted. To check understanding, it is a good idea to have a workshop with stakeholders to confirm their role and how they interact with other stakeholders and systems. This could also help identify other unforeseen stakeholders or systems.

Gathering requirements from the stakeholders and other sources

There are several approaches that can be used to find out from people what their requirements are: interviews, workshops, working alongside users (as a user), and observing users at work. With all these methods, a “why”-style question or an open question is very useful to ask to get an understanding of what a user does or wants. To be effective, interviews and workshops need two people to work together: the requirements engineer and someone to record the outcome. This is on the basis that it is very difficult for one person to talk, ask, watch people, listen well, interpret results, all while recording everything. Things are likely to be missed. An added advantage is that the outcome can be documented and fed back quickly for confirmation by the stakeholders. Workshops are an invaluable way to solicit and understand requirements, as getting people together is more interactive and gives stakeholders the opportunity to propose, evaluate and agree on requirements. Of course, there are other ways to gather requirements: reading problem reports; meeting the helpdesk and support teams; talking to trainers, consultants and customers; reviewing comparable products and looking at existing designs, specifications and contracts.

Structuring requirements

Having a good structure to requirements will help us to understand them, while making them more accessible and easier to check. But what structure might be appropriate? A key question to ask is, “What is the system going to achieve for the customers or users?” The answer could be, for example, “to ensure new insurance business is recorded promptly,” or “to ensure that outstanding debt is regularly pursued,” or “to provide a virtual exchange for small businesses.” Each of these statements represents a “goal” that the system needs to support. These are clearly at quite a high level and need to be broken down into lower-level statements of requirement, such as “the customer support operator will capture policyholders’ details over the phone,” “the system will automatically produce a monthly statement of outstanding invoices for all customers with aged debt,” and “the system will route an incoming call to the designated mobile device matching its virtual extension number.” This “decomposition” would then be taken further to provide detailed explanation of the requirements (What are the policyholder’s details? What does aged debt mean? How does a mobile device get designated a virtual extension number – or vice versa?).

By sequencing these statements of requirements, it is possible to build up a scenario of actions necessary to achieving the final goal. Use cases are an example of how this might be documented. For testing, especially in the latter stages of systems test and acceptance test, these scenarios can provide essential input to the design and development of our tests.

Context: What about those non-functional requirements?

Almost every requirement is qualified by context through some sort of constraint (often referred to as, rather confusingly, non-functional requirements). An obvious constraint is that of performance, e.g. 95% of all such routing must occur within a maximum of 5 seconds of the call being received. ISO 9126 (the four-part software quality standard) provides a good reference point for these constraints (the so-called “-ilities”): reliability, usability, maintainability, portability and efficiency.

Where should such requirement constraints be documented? Some constraints are likely to apply to a specific requirement or subset of requirements and thus might be put with those requirements (as in the example above). Other requirements, such as portability, may be at the system level and thus might be better stored entirely separate under their own goals, e.g. all our products must operate on Windows, UNIX, and Linux platforms.

Writing requirements

So what actually makes a good written requirement? “Keep it simple” would certainly seem to be a good guideline. Long, wordy and complex requirements are likely to confuse rather than provide clarity. You might like to consider these:

  • Use one simple, short, direct sentence (don’t waffle; it’ll cloud the issue)
  • Avoid jargon, abbreviations, and acronyms, etc. wherever possible (having to continually
  • refer to a glossary is a nuisance)
  • Don’t use obscure or long words (if you think someone will need to get a dictionary out then don’t use it)
  • Start by naming the user, e.g. “The call center operator will…” (this makes it clear who is affected by the requirement)
  • All requirements should have a single desired result, e.g. delete the customer’s account (otherwise it’s not one requirement)
  • Statements must be verifiable, e.g. 45 concurrent users (it must be measurable)
  • Don’t include exception words such as when, but, except, unless, although, always, perhaps, may, might, etc. (as these often infer multiple requirements or possibilities)
  • Don’t put design or solutions into the requirements (they belong in design documents, not in requirements)
  • Don’t put plans – dates, milestones, etc. – into the requirements (they should be in, well, plans!)
  • Don’t specify the impossible, e.g. handle all expected failures (you’ll be disappointed and it’s not verifiable anyway)

There might be other worthwhile considerations, such as writing in present tense rather than future tense. Future tense feels right for new developments but can be confusing for those maintaining the system once implemented.

Checking and reviewing the requirements

You should be on familiar ground here as many testers have done an 8-point check as part of Static Testing. However, some of the points raised above might help you extend the range of checking during Static Testing. However, a key point for the requirements engineer is that the requirements need to be checked before they are passed onto the design and development teams. Often, by the time we do our 8-point check it is after the design and even coding has already been completed, with much money and time having already been spent.

Checking needs to take place immediately after the structure for the requirements has been established so that the sequence and organization of the requirements can be confirmed with the users. Once this is done then the requirements themselves can be checked in detail, individually and as a set. The results of this would then be published to stakeholders who would attend a review meeting to decide what to do with the comments and agree to changes.

Most of these checks (but perhaps not all) should seem familiar:

  • Is it clear?
  • Is it as short as it can be?
  • Does it apply to a defined type of user? (NB the user could be a system)
  • Is it prioritized?
  • Is it verifiable?
  • Is it a single requirement?
  • Is its source shown?
  • Is it uniquely identified?
  • Is it really a requirement, or is it design or solution-related?
  • Is the set of requirements complete?
  • Is the set of requirements consistent?
  • Is the set of requirements realistic?
  • Is the set of requirements balanced (i.e. same level of detail)?

Finally, what about agile?

A very good question! Incremental development methods, such as agile, tend to take the formulation of requirements very strongly down the workshop route, with much interaction and discussion with interested stakeholders taking place on a regular basis. The formulation of good requirements, even (or perhaps especially) in such a dynamic environment, is likely to be key to a successful outcome of the project. The difference will be that the definition of the requirements is itself iterative. I’ll leave that to the agile experts to explain – see Other Sources below.

Conclusions and questions

  • Looking at requirements through the eye of the author could help us improve the checking in our Static Testing
  • Our 8-point check could be a) extended to incorporate additional checks such as those regarding sets of requirements and b) further explained to describe what a good requirement should contain.
  • Could identify changes to our Static Testing delivery product
  • Our involvement in requirement reviews can be incorporated quite well into a project. Is there scope for getting involved earlier? Could we offer a requirement checking delivery product?
  • This process should make us think about the future of testing
  • With the rise of agile development how long will it be before we are involved earlier and will be helping to formulate requirements? What can we do to be ready for this? More specifically, what would you like us to do to help you be ready for this?

Reference sources

Alexander, Ian and Stevens, Richard. “Writing Better Requirements.” Addison Wellesley Publishing Company Incorporated, 2002.

Gilb, Tom and Graham, Dorothy. “Software Inspection.”  Addison Wellesley Publishing Company Incorporated, 1993.

For requirements management in agile see: