Four More Core Software Requirements Practices

Two previous articles described the?six most important requirements practices ?that every software team should perform, as well as?six more important requirements practices . Here are four more core practices that, again, virtually every software or systems development project will find valuable. This article is adapted from?Software Requirements Essentials: Core Practices for Successful Business Analysis ?by Karl Wiegers and Candase Hokanson.

Practice #13: Identify empowered decision makers

Every project faces a continuous stream of decisions large and small. There are many types of requirements-related decisions. You’ll need to resolve conflicting requirements both within a user class and across user classes. You’ll have to resolve conflicting priorities among different stakeholder groups, set requirement priorities, and adjust them as reality happens.?Quality attributes often conflict , demanding trade-off choices. And someone must define the scope of each development increment and elect when and how to modify that scope in view of new requirements, evolving business needs, and other factors.

The project initiators should identify the key decision makers for such issues — before they confront their first significant decision. Each such group should select a decision leader to coordinate their activities and provide clear lines of responsibility, authority, and accountability.

In addition, the group should agree upon how they’ll reach their conclusions: their decision rule. Possible decision rules include unanimous vote, plurality vote, consensus, decision leader decides with or without input from others, and delegation. There’s no universally “correct” decision rule. But however you choose to make decisions, recording significant decisions and their rationale can prevent the same issues from reappearing later.

Practice #14: Assess data concepts and relationships

All software applications create, consume, manipulate, or delete data. We can think of data as the glue that connects all the other requirement types; alternatively, functionality exists to process data. Begin your data exploration by acquiring a full list of data objects: the logical representation of system information. Look for significant data objects in places like these.

• Pick out the nouns that appear in descriptions of the business problem, solution concept, processes, user requirements, state-transition diagrams, and event-response tables.
• The labels on the lines of an ecosystem map or context diagram flows identify high-level data objects.
• When stakeholders mention items such as a customer, order, or address, those likely refer to data objects needed in the solution.
• Descriptions of reports, displays, and other outputs give clues regarding data items the system must either receive as inputs or create.

After identifying likely data objects (entities), you can create a data model to show the logical connections between them (relationships). The?entity relationship diagram?or ERD is a popular convention for drawing data models, like the example in Figure 1. ERDs can represent conceptual, logical, or physical data views. Other tools for describing a system’s data concerns include the data flow diagram and data dictionary.

Once you have the data objects in hand, look for functionality associated with them. A helpful acronym is CRUD: Determine how an instance of each data object is?Created,?Read,?Updated, or?Deleted within the solution. Look for data objects that are created but never used or stored, and for objects that are used by processes but never explicitly read or created. Understand where each piece of data comes from and how the system inputs it. Data output requirements reveal the functionality needed to build the output displays. Ask your stakeholders about business rules and other constraints that lead to derived functionality to comply with them.

Without careful data elicitation and analysis, you might face problems like fixing data length mismatches after the system’s launch. It’s not fun.

Practice #15: Create requirements models

Text is not the only way, and sometimes not the best way, to represent requirements knowledge. Visual requirements models — diagrams— provide a great way to look at requirements information from different perspectives. Models aid requirements analysis in several ways.

• Models provide a context to see where each requirement fits in the overall problem or solution space.
• Violations of modeling rules can reveal omissions and errors.
• Models help the team discover missing requirements by ensuring that each element the solution introduces (process flows, system states, data objects, and so forth) has corresponding functionality defined to implement it.
• When multiple models that show different views of the same information do not agree, that conflict can reveal incorrect, missing, or unnecessary requirements.

Dozens of models are available for representing business processes, requirements, architectures, and designs. They’re collected in several modeling languages, including BPMN, RML, structured analysis, SysML, and UML. Avoid inventing your own notations unless you find that none of the available models will communicate what you’re trying to show (which is unlikely).

You don’t have to model every aspect of your system. Create models that will enhance the team’s understanding of those portions of the problem or its solution that are especially novel, complex, or risky.

After you’ve created an initial model, walk through it with appropriate stakeholders. Suppose you’re developing a billing system. You might draw a state-transition diagram like the one in Figure 2 to describe the life cycle of an invoice for a construction job. Show the various possible statuses the invoice can have in the boxes. The arrows show the permitted transitions between various invoice statuses. Walking through this visual representation helps stakeholders identify anything that’s incorrect, missing, or obsolete. It’s a lot faster to modify a model than to rewrite software when the users discover a problem.

Practice #16: Write requirements in consistent ways

Whenever you see the phrase “writing requirements,” mentally convert that to “representing requirements knowledge.” There are many alternatives to natural-language text. The key is to choose a representation that will communicate a particular piece of information clearly, efficiently, and accurately. Consistently following some patterns and guidelines makes writing textual requirements easier.

Functional requirements traditionally use the keyword?shall?to state how the system should behave under certain conditions or a capability it will provide. Common patterns for such requirements include:

The <user class> shall be able to <do something>.

The system shall <let the user class do something>.

When <some conditions are true or something happens> the system shall <do something>.

The first pattern focuses on what a user can do; the second and third focus on what the system does. Here’s an example:

Security.Admin.1. The homeowner shall be able to change the security system’s passcode.

Agile project teams employ user stories to document desired system capabilities. A user story identifies who wants the capability, what capability they want, and why:

As a <type of user>, I want to <perform some task> so that I can <achieve some goal>.

Returning to the security system example, we could write this user story:

As a homeowner, I want to change my security system’s passcode so that I can prevent the previous owner from getting into my house.

There are several good practices to follow when writing requirements of any type:

• Write in short, declarative sentences.
• Write in the active voice to make it clear which entity performs each action.
• Refer to specific user classes rather than to a generic “user.”
• If there’s any possibility of ambiguity, name the system in question rather than simply saying “system.”
• Avoid bullet lists, as there’s no good way to refer to a particular bullet item.
• Avoid combining multiple independent requirements with words like?and,?not,?or,?but,?except, and?else.

The overarching objective of writing requirements is always clear and effective communication. Anything that facilitates that goal is good; anything that inhibits it is evil.

Along with the?first six important practices ?we described and the?second group of six more , and a?final set of four practices , these four activities make life easier and success more likely on every software and systems project. It’s less painful to build these practices into your plans from the beginning than to deal with the problems that can result later on if you neglect them.

================

This article is adapted from?Software Requirements Essentials: Core Practices for Successful Business Analysis ?by Karl Wiegers and Candase Hokanson. Karl is the author of numerous books on software development and other topics, including?Software Requirements ?(with Joy Beatty),?Software Development Pearls ,?and?The Thoughtless Design of Everyday Things . Candase is a business architect at ArgonDigital. She has written numerous articles on best practices in requirements management and agile product ownership.