Tag: Requirements

We Don’t Need No Stinkin’ Code: Testing Software Requirements

Written by Karl Wiegers on January 27, 2021. Posted in Articles. 1 Comment on We Don’t Need No Stinkin’ Code: Testing Software Requirements

Someone once asked me when you can begin testing software. “As soon as you’ve written your first requirement, you can begin testing,” I replied.

It’s hard to visualize how a system will function by reading some requirements. Tests that are based on requirements make the expected system behaviors more tangible. Even the simple act of designing tests reveals many requirements problems long before you can execute those tests on a running system.

Requirements and Tests

Tests and requirements present complementary views of the system. Creating multiple views of a system—written requirements, diagrams, tests, prototypes, and so forth—provides a much richer understanding of the system than can any single representation. Some agile development methods emphasize writing user acceptance tests from user stories in lieu of writing detailed functional requirements. Thinking about the system from a testing perspective is valuable, but that approach still leaves you with just a single representation of requirements knowledge, so you must trust it to be correct.

Writing black-box (functional) tests crystallizes your vision of how the system should behave under certain conditions. Vague and ambiguous requirements will jump out at you because you won’t be able to describe the expected system response. When business analysts (BAs), developers, and customers walk through tests together, they’ll codify a shared vision of how the product will work and increase their confidence that the requirements are correct.

A personal experience brought home to me the importance of combining test thinking with requirements specification. I once asked my group’s UNIX scripting guru, Charlie, to build a simple e-mail interface extension for a commercial defect-tracking system we had adopted. I wrote a dozen functional requirements that described how the e-mail interface should work. Charlie was thrilled. He’d written many scripts for people, but he’d never seen written requirements before.

Unfortunately, I waited a couple of weeks before I wrote the tests for this e-mail function. Sure enough, I had made an error in one of the requirements. I found the mistake because my mental image of how I expected the function to work, represented in about twenty tests, was inconsistent with one of the requirement. Chagrined, I corrected the defective requirement before Charlie had completed his implementation, and when he delivered the script, it was defect free. It was a small victory, but small victories add up.

Conceptual Tests

You can begin deriving conceptual tests from user requirements early in the development process. Use the tests to evaluate functional requirements, analysis models, and prototypes. The tests should cover the normal flow of each use case, alternative flows, and the exceptions you identified during elicitation and analysis. Similarly, agile acceptance tests should cover both expected behaviors and exceptions.

Consider an application called the Chemical Tracking System. One use case, “View a Stored Order,” let the user retrieve a particular order for a chemical from the database and view its details. Some conceptual tests are:

User enters order number to view, order exists, user placed the order. Expected result: show order details.
User enters order number to view, order doesn’t exist. Expected result: Display message “Sorry, I can’t find that order.”
User enters order number to view, order exists, user didn’t place the order. Expected result: Display message “Sorry, that’s not your order. You can’t view it.”

Ideally, a BA will write the functional requirements and a tester will write the tests from a common starting point, as shown in Figure 1. Ambiguities in the user requirements and differences of interpretation will lead to inconsistencies between the views represented by the functional requirements, models, and tests. Those inconsistencies reveal errors. As developers translate requirements into user interface and technical designs, testers can elaborate the conceptual tests into detailed test procedures.

Figure 1. Development and testing work products derive from a common source.

A Testing Example

Let’s see how the Chemical Tracking System team tied together requirements specification, analysis modeling, and early test-case generation. Here are some pieces of requirements information, all of which relate to the task of requesting a chemical.

Use Case. A use case is “Request a Chemical.” This use case includes a path that permits the user to request a chemical container that’s already available in the chemical stockroom. Here’s the use case descriptionUse Case. A use case is “Request a Chemical.” This use case includes a path that permits the user to request a chemical container that’s already available in the chemical stockroom. Here’s the use case description.

The Requester specifies the desired chemical to request by entering its name or chemical ID number. The system either offers the Requester a container of the chemical from the chemical stockroom or lets the Requester order one from a vendor.

Functional Requirement. Here’s a bit of functionality associated with this use case:

If the stockroom has containers of the chemical being requested, the system shall display a list of the available containers.⦁ If the stockroom has containers of the chemical being requested, the system shall display a list of the available containers.
The user shall either select one of the displayed containers or ask to place an order for a new container from a vendor.

Dialog Map. Figure 2 illustrates a portion of the dialog map for the “Request a Chemical” use case that pertains to this function. A dialog map is a high-level view of a user interface’s architecture, modeled as a state-transition diagram. The boxes in this dialog map represent user interface displays (dialog boxes in this case), and the arrows represent possible navigation paths from one display to another.

Figure 2. Portion of the dialog map for the “Request a Chemical” use case.Figure 2. Portion of the dialog map for the “Request a Chemical” use case.

Test. Because this use case has several possible execution paths, you can envision numerous tests to address the normal flow, alternative flows, and exceptions. The following is just one test, based on the flow that shows the user the available containers in the chemical stockroom:

At dialog box DB40, enter a valid chemical ID; the chemical stockroom has two containers of this chemical. Dialog box DB50 appears, showing the two containers. Select the second container. DB50 closes and container 2 is added to the bottom of the Current Chemical Request List in dialog box DB70.

Ramesh, the test lead for the Chemical Tracking System, wrote several tests like this one, based on his understanding of how the user might interact with the system to request a chemical. Such abstract tests are independent of implementation details. They don’t describe entering data into specific fields, clicking buttons, or other interaction techniques. As development progresses, the tester can refine these abstract tests into specific test procedures.

Now comes the fun part—testing the requirements. Ramesh first mapped the tests against the functional requirements. He checked to make certain that every test could be “executed” by going through a set of existing requirements. He also made sure that at least one test covered every functional requirement.

Next, Ramesh traced the execution path for every test on the dialog map with a highlighter pen. The yellow line in Figure 3 shows how the preceding test traces onto the dialog map.

Figure 3. Tracing a test onto the dialog map for the “Request a Chemical” use case.

By tracing the execution path for each test on the model, you can find incorrect or missing requirements, improve the user’s navigation options, and refine the tests. Suppose that after “executing” all the tests in this fashion, the navigation line in Figure 2 labeled “order new container” that goes from DB50 to DB60 hasn’t been highlighted. There are two possible interpretations:

That navigation isn’t a permitted system behavior. The BA needs to remove that arrow from the dialog map. If you have a requirement that specifies the transition, that requirement also needs to go.
The navigation is a legitimate system behavior, but the test that demonstrates the behavior is missing.

When I find such a disconnect, I don’t know which possible interpretation is correct. However, I do know that all of the views of the requirements—textual, models, and tests—must agree, so there’s clearly something wrong.

Suppose that another test states that the user can take some action to move directly from DB40 to DB70. However, the dialog map doesn’t contain such a navigation line, so the test can’t be “executed:” you can’t get there from here. Again, there are two possible interpretations:

The navigation from DB40 to DB70 is not a permitted system behavior, so the test is wrong.
The navigation from DB40 to DB70 is a legitimate function, but the requirement that allows you to execute the test is missing.

In these examples, the BA and the tester combined requirements, analysis models, and tests to detect missing, erroneous, or unnecessary requirements long before any code was written. Every time I use this technique, I find errors in all the items I’m comparing to each other, quickly and cheaply

As consultant Ross Collard pointed out, “Use cases and tests work well together in two ways: If the use cases for a system are complete, accurate, and clear, the process of deriving the tests is straightforward. And if the use cases are not in good shape, the attempt to derive tests will help to debug the use cases.” I couldn’t agree more. Conceptual testing of software requirements is a powerful technique for discovering requirement ambiguities and errors early on.

Karl Wiegers is Principal Consultant at Process Impact. He’s the author of numerous books and articles on software development, project management, design, quality, chemistry, military history, and other topics. This article is adapted from Software Requirements, 3rd Edition by Karl Wiegers and Joy Beatty. Karl’s latest book is The Thoughtless Design of Everyday Things.

For the Love of Data: An Overview of Data Modeling for BAs

Written by Richard Larson on January 21, 2021. Posted in Articles.

I have always been a data fanatic. It started when I was a programmer analyst and learned to love such arcane data structures as ISAM (a relic), VSAM (simple, but efficient), and later DB2 (powerful and flexible).

My recent database exposure has been MySQL for websites, but only as a BA.

Mind you, I love process work, too, but maybe I just prefer the structure of database fields, columns, rows, and tables. Or maybe it is being able to query and manipulate the data to provide information useful for doing business or making decisions. Whatever the reason, I have long had an appreciation for and a love of analyzing data needs and turning them into robust logical or business data models.

So, let us get started with this overview of logical data modeling, which is divided into three basic steps.

Step 1: Entities

The central element in a logical model is an entity. It represents the people, places, things, processes, and events in an organization. All operational data fits into specific entities and if done correctly, only one. Note that physical databases might introduce redundancy for performance reasons. Take for instance a simple banking example with four entities in italics. Your money sits in accounts, which have deposits and withdrawals, and periodic statements are sent to one or more of your addresses.

Entities by convention are named with a singular, business-oriented noun. For our example, the entities might well be called Account, Transaction (an abstraction of deposit or withdrawal), Statement, and Location (instead of address). Choosing an appropriate name is harder than it may seem. I have witnessed teams toil over the best name and level of abstraction. The effort is worth it, though, to provide long-lasting data structures with meaningful names to the organization. Physical databases implement entities as tables or files.

Step 2: Relationships

Once the entities in question are identified, it is time to tie appropriate ones together into what are called relationships. Relationships are used to eventually tell the database engine which data elements belong together and should be retrieved together. In a physical database, relationships are expressed using keys, which are covered below. Once the entities in question are identified, it is time to tie appropriate ones together into what are called relationships. Relationships are used to eventually tell the database engine which data elements belong together and should be retrieved together. In a physical database, relationships are expressed using keys, which are covered below.

For our banking example, an Account has a relationship to the Transactions which identify the accounts a deposit or withdrawal applies to. A Statement is a collection of Transactions, so a relationship is needed there. Finally, Statements are sent to Locations, whether a physical address or an electronic one. For our banking example, an Account has a relationship to the Transactions which identify the accounts a deposit or withdrawal applies to. A Statement is a collection of Transactions, so a relationship is needed there. Finally, Statements are sent to Locations, whether a physical address or an electronic one.

Here are the categories of relationships in a logical model, with examples from the banking application shown in Figure 1: Here are the categories of relationships in a logical model, with examples from the banking application shown in Figure 1:

⦁ One to one (rarer than you think; maybe the bank needs a credit report entity and for some reason limits them to only one credit report per account.)

⦁ One to Many (an account can have many transactions, but a transaction belongs to only one account.)

⦁ Many to Many (statements might be sent to multiple locations and a given location might receive multiple statements.)

Our small banking example might look like the image in Figure 1 when depicted using “crow’s foot” notation, a common data modeling diagramming style. (There are other styles, but “crow’s foot” has been around a long time and is commonly used.) The “crow’s feet” represent “many” and the bars show “one.” The “O” symbols on the model designate “optional” or zero associations. Our small banking example might look like the image in Figure 1 when depicted using “crow’s foot” notation, a common data modeling diagramming style. (There are other styles, but “crow’s foot” has been around a long time and is commonly used.) The “crow’s feet” represent “many” and the bars show “one.” The “O” symbols on the model designate “optional” or zero associations.

To interpret the diagram, we can say an Account has at least one Transaction but likely will have many. A transaction applies to a single account and is not optional. A transaction appears on a single statement, but a statement can have “zero, one, or many” transactions on it. A Statement is sent to one or more Locations, while a given Location may receive no Statements, but can receive many over time. The above diagram is commonly referred to as an “Entity-Relationship Diagram” or ERD for short.

Step 3 – Attributes

After relationships are identified in a model, specific data the business wants to capture and report on can be added to the entities. The data elements are called attributes and could be added as soon as entities are defined, but it is easier with relationships in place. In a physical database attributes become fields or columns of data. After relationships are identified in a model, specific data the business wants to capture and report on can be added to the entities. The data elements are called attributes and could be added as soon as entities are defined, but it is easier with relationships in place. In a physical database attributes become fields or columns of data.

Like entities, attributes are labeled with a singular noun. For our banking example, a few facts pertaining to each entity are shown in Figure 2. Like entities, attributes are labeled with a singular noun. For our banking example, a few facts pertaining to each entity are shown in Figure 2.

Primary keys

The # in the example above represents an important concept in a data model called the “primary key” or “unique identifier.” Each entity needs an attribute or attribute combination with values unique to each occurrence of the entity. To distinguish one transaction from another the “# transaction number” attribute must have unique values for each separate transaction. An arbitrary identifier (sometimes called a “one-up” due to its sequential nature) is frequently used for this purpose. The # in the example above represents an important concept in a data model called the “primary key” or “unique identifier.” Each entity needs an attribute or attribute combination with values unique to each occurrence of the entity. To distinguish one transaction from another the “# transaction number” attribute must have unique values for each separate transaction. An arbitrary identifier (sometimes called a “one-up” due to its sequential nature) is frequently used for this purpose.

Foreign Keys

To solidify relationships between entities, “foreign keys” are used. A foreign key is a primary key of one entity added to the entity on the other side of the relationship. The Account-Transaction relationship is bonded using the account number key of Account placed in the Transaction entity represented with the “(FK)” in the example. Note: the exact way of showing attributes, primary keys, and foreign keys is usually determined by your organization’s modeling software and standards. To solidify relationships between entities, “foreign keys” are used. A foreign key is a primary key of one entity added to the entity on the other side of the relationship. The Account-Transaction relationship is bonded using the account number key of Account placed in the Transaction entity represented with the “(FK)” in the example. Note: the exact way of showing attributes, primary keys, and foreign keys is usually determined by your organization’s modeling software and standards.

Attributes are meant to represent single facts and if you discover an attribute that repeats or is in the wrong entity, then it needs to be adjusted using “normalization.” The Statement-Location relationship causes repeating attributes due to its Many-Many relationship. Normalization would solve this, and the topic could be an entire article on its own. Suffice it to say that “an attribute must be dependent on the key, the whole key, and nothing but the key.” The quote is attributed to a past database guru and summarizes how attributes should be added to entities. Attributes are meant to represent single facts and if you discover an attribute that repeats or is in the wrong entity, then it needs to be adjusted using “normalization.” The Statement-Location relationship causes repeating attributes due to its Many-Many relationship. Normalization would solve this, and the topic could be an entire article on its own. Suffice it to say that “an attribute must be dependent on the key, the whole key, and nothing but the key.” The quote is attributed to a past database guru and summarizes how attributes should be added to entities.

Summary

Data modeling is fascinating to me because it helps turn the ambiguity of possible data needs into a precise depiction of business rules and requirements. I have come to realize that constructing a robust data model helps us discover the meaning of the data to the organization. Focusing on the meaning of data has helped me to resolve intricate normalization issues that inevitably come up. Hopefully this article provides a quick introduction or refresher to help you get the most out of your data work. Data modeling is fascinating to me because it helps turn the ambiguity of possible data needs into a precise depiction of business rules and requirements. I have come to realize that constructing a robust data model helps us discover the meaning of the data to the organization. Focusing on the meaning of data has helped me to resolve intricate normalization issues that inevitably come up. Hopefully this article provides a quick introduction or refresher to help you get the most out of your data work.

What does success look like?

Written by Melissa Anstedt on December 30, 2020. Posted in Articles.

I like to challenge Business Analyst to look at requirements as an opportunity to define what success looks like for the requestor.

Too often teams fall into a trap focused on prescriptive requirements that are to serve as a roadmap for developers and testers to know what to build and how to make sure it is working. When you start viewing requirements with this prescriptive lens you lose sight of the overall objective and stifle creativity that comes from meeting problems with fresh solutions.

Why do we need requirements?

Requirements are the union between the customer and the solution. They define expectations and how to meet them. Requirements illustrated through user stories or through waterfall documentation play a large role in helping shape technical solutions and the steps it will take to implement. They also lay out the acceptance criteria and use cases for said requested change. This leads to creation of test scenarios and the ability for the team to sign off and say, “yes this is what I requested. It checks all the boxes”.

But what if we offered more with our requirements. What if we could connect those requirements to broader objectives that the customer is trying to solve? What if we could get requirements in such a way that could lead to solutions to problems, they maybe never realized they had? These solutions could ultimately lead to increases in productivity, profits, and/or customer satisfaction. When you shift the mindset that requirement gathering sessions are to get “technical specifications”, to an opportunity to learn about a problem and bring it back to the group for a creative solution; meaningful technical solutions begin to emerge that are readily adopted by users and integrated into processes.

How do I make more out of requirements sessions?

When I was early in my career as a business analyst, I would leave requirements gathering sessions and think, “How am I supposed to do this, when the users don’t even know what they want?”. This usually came from an approach that looked something like this:

Me: “So let’s talk about what “xyz” will look like and what it will do”

Them: “Well I won’t know what it can do until you build it”

There came a point when I realized, that it isn’t the customers job to know how to give me requirements. These requestors represent a segment of the company and were hired to be the best accountant, lawyer, analyst, etc. It is my job to know how to elicit requirements, and sometimes it will require some creativity and perfectly placed questions to make the most out of my requirements gathering session.

Requirement Elicitation

The best questions to use in a requirement gathering session are those that create dialogue and conversation. The more people are talking about a requested change, the more information can be gathered by the Business Analyst to bring back to the developers/testers for a solution. Even better than a rousing conversation, is a moment of silence. If you can ask a question to the customer that causes them to stop and pause and say something like ‘I hadn’t thought of that before”, you have asked a great question. These questions cause people to think through exactly what it is they are looking for and more importantly how it will look if it is successful, and how they will ultimately adopt said change.

Here is a sample of these types of questions that can be used to really drive at sound requirements, that will ultimately lead to technical solutions that users adopt.

If this project/enhancement does not happen, what would be the impact?
Is there anything in this process/system that you would not change?
If this system/change looked exactly how you pictured it, what would the process look like? How would you interact with it?
What would be your best measure of success?
Why do you think we need ”xyz”? How did we get here?
What have you tried in the past?
What are the top problems/challenges that your business faces? Why?

Finding the right time to ask one of these questions takes practice, and there is no better time than now to start!

What Use Case to Use?

Written by Jenny Quillian on December 9, 2020. Posted in Articles.

The Use Case is a standard tool in the BA toolkit, and like most tools they come in different shapes and sizes for different jobs.

During Business Analysis Planning it is important to identify the appropriate use case format for the project needs. At the high end we have a multi-page highly regulated requirements template. The base model is a single actor and basic flow. Between these is the textbook version with complex flows. This article looks at these use case formats and design influences to consider during your Business Analysis Planning.

Use Case Formats

Simple Flow Use Case
Complex Flows Use Case
Highly Prescribed Use Case

Simple Flow use cases describe the interaction of a single actor along one basic flow. This format can be used as the starting point for a more complex effort, as a placeholder for planning purposes, or as the final deliverable for a simple project. This format is similar to a user story, with post conditions instead of benefits.

Complex Flow use cases include alternate flows, triggers, business rules, post and exit conditions. The degree of complexity should be determined by the stakeholder needs and perspectives. For business users the documentation must be readable so that they can follow and agree that you have captured their needs correctly. For the architects and developers, the details must be specific enough to translate into units of development. For the testing teams the documentation must provide clear inputs and outputs of success so that they can formulate test cases.

Highly Prescribed use cases have a multi-page template with approved instructions to complete each section. There are projects which require such discipline, but I have also worked on projects where the template became the end rather than the means, and the degree of detail slowed down the project and produced wasteful documentation.

Design Factors

Use Case formats will be influenced by:

Funding model
Requirements complexity
Rate of change
Regulatory environment
Project methodology
Project phase
Build or Buy

Funding Model

Organizational funding models may impose a need for provide for detailed requirements well in advance of the project development phase, in order to compete for funding. A use case that identifies all potential steps, alternate flows, business rules and usage estimates can be useful to assist with cost estimates. Tight funding oversight models will ask for more detailed documentation than open models.

Requirements Complexity

Retail web pages for major sellers can be large and complex because of the product offerings, but the system requirements themselves are repetitive and reusable and changes easily delivered with a user story or simple use case.

A new system with complex requirements needs more detailed documentation than an informational web page. A new system with many business rules needs detailed documentation and requirements tracing to ensure proper coverage. Integrated systems need a degree of rigor ad traceability to ensure that front end changes do not break upstream or downstream systems such as integrated re-order or delivery systems.

Rate of Change

The retail web pages are repetitive but require rapid changes to meet demand and marketing plans. The requirements documentation cannot stand in the way of rapid delivery.

From another perspective, detailed requirements documentation that can be reviewed in the change management process can help slow down a rush delivery and prevent embarrassing releases.

Regulatory Environment

Systems that are governed by external regulations need detailed requirements documentation that can be read and understood by multiple stakeholders so that all affected parties are able to understand and approve the inputs and outputs of the system to be delivered. Systems that collect personal information must be able to demonstrate that the correct information is being captured and the appropriate security will be in place to protect this information from misuse.

Project Methodology

Waterfall projects tend to require detailed requirements. Agile projects prefer minimal documentation, user stories, and simple use cases if any.

Project Phase

Documentation detail may expand or contract during the project phases. As discussed above, projects may require detailed requirements documentation for early feasibility and cost analysis exercise, but they may then drop down to user stories for the development and delivery. Other projects may require only simple use cases to outline a concept, and then expand on the use case flows and details during the requirements phase.

Build or Buy

If the project includes a build or buy decision, then a simple use case format that can be transferrable to a matrix of acceptance and evaluation criteria will be most useful when comparing solution options.

Summary

Use Cases are a valuable business analysis tool that come in multiple flavors. As part of the Business Analysis Planning step the Business Analyst should identify the degree of rigor and detail that the project and the stakeholders require and select the appropriate use case format(s) to use during the project.

Taking responsibility for the outcome

Written by Shane Turner on November 25, 2020. Posted in Articles. 1 Comment on Taking responsibility for the outcome

As a Junior Business Analyst who’s about to go into a meeting to report on why our latest deployment into production had so many bugs –

it made me think about all the missed opportunities and potential questions I could have asked myself to catch them sooner.

As a business analyst, it’s my job to brief the team on the features that need to be developed, and ensure they get the designs and documentation to ensure a smooth, (hopefully) bug-free implementation that can be thoroughly tested before release. So why did we have four bugs then?

Assume responsibility

Asking yourself these questions may help to pinpoint where the issue originated:

1. How often are change requests initiated (not due to a change in business requirements), within the project – due to incomplete or incorrect requirements?

2. How often are bugs added to the backlog, as a result of unclear or misunderstood requirements?

How often are the designs or documentation being updated to re-clarify the requirements which have been misunderstood by the developers?

How often are the testers missing potential test scenarios due to lack of knowledge of the scope of the work being implemented?

How often are additional backlog items and stories created due to lack of completeness within the specifications?

How often does the client point of missing aspects of features or stories which have made their way into the staging environment or production due to a poorly fleshed out requirements spec?

(Less) Consistency is key.

I found myself answering ‘frequently’ to too many of the above questions, which not only impacts the overall deadline of the project, but it also costs our clients a fair penny in project costs.

Striving to be a better BA does not mean perfection from day 1, but rather small improvements over time – and that means starting with an honest reflection of where you may be falling short.

Don’t fall into the blame game of, “Oh, but the developer should have thought of this scenario”, or “Oh the testers should have picked it up”. You created the spec, you were there for the grooming, and the planning – and had the opportunity to glance over the test cases before development began. Take ownership of the outcome.

So where did I fall short this time? Even though my spec was well thought out AND I provided the testers with a list of test scenarios to consider, the one thing I didn’t do – was consider the scope of the system being impacted in the development -resulting in an entire segment of the system going untested.

Sometimes we’re so focused on the little details that we forget to take a step back and take in the bigger picture.