I wrote this paper for my Technical Writing for the Professions class. I conducted more than 30 interviews with a group of requirements analysts, software testers, and software developers to discover the effectiveness of the requirements documentation developed within one organization. This paper discusses the findings of that research and recommends several actions for organizations facing similar issues.

1. The
Testers’
Chronicle:
A Tale of Bad
Requirements
and the Chaos
of Change
• Does Agile fit your
project?
• Involving testers in the
requirements discussion.
• The requirements keep
changing!
• What are good
requirements and why
does it matter?

2. “Massive chaos!” uncomfortable) (Derfler, 2001). The tester then
places more emphasis on scenarios that are
“Scrambled eggs!” critical to the customer and develops test
scenarios that more closely resemble actual
“Miserable!” customer usage. Extra testing on high priority
and high risk areas tends to find important
“Test would be lost!” defects.
What sort of doomsday do these But, when the testers are not included in the
comments reflect? These are the requirements sessions, they must try to get this
responses of software testers at Company kind of perspective by other means. For example,
they read the Vision document which defines the
Z when asked, “What would happen if we
project scope. In it they find statements about
didn’t document requirements?”
the business opportunities and the problems
“We couldn’t write tests. All the tests are that the new system must address, along with a
based on the requirements. If the requirements list of stakeholder needs and features.
analysts didn’t document them, I’d have to do it Unfortunately, these requirements are often
myself.” Clearly, testing at this company is rather sketchy. Several of the testers expressed a
wish for not only more detail in these
heavily dependent upon requirements
documentation. In many ways, it is an descriptions, but also diagrams and pictures to
unfortunate dependency. The quality of the help explain the bigger context about what is
requirements and their constant change make needed and why.
testing unnecessarily inefficient at Company Z.
Whether or not they get a clear picture of the
project scope from the Vision document, the
Test depends on requirements. The test
next recourse for the testers is the Solution
development process demonstrates the testers’
Requirements Specification (SRS) which should
dependency on the requirements. Ideally,
contain the detailed requirements. Occasionally,
analysts at Company Z include the testers in the
this document provides just the kind of detailed
requirements gathering sessions with the
requirements needed. More often, this is where
business customer so they can understand what
the real trouble begins. Typical problems are:
the customer needs and why. Kurt Derfler
confirms the benefit of including the testers and • The requirements are not detailed enough.
adds that testers will also identify risky
requirements during these sessions (those that • The requirements are vague.
they observe to make the developers

3. • The requirements are not testable. Even in that utopia, there is one more hazard to
tester joy: Change management.
• The requirements inappropriately dictate
design details. While change management problems are not
inherent to the waterfall life cycle model which is
If the SRS fails them, the testers have one used at Company Z, longer development cycles
more hope: the use cases. They may happily find certainly provide more opportunity for glitches
that the use cases are so wonderfully detailed (Goodpasture, 2011). During the months or years
that they can actually write the test scripts between writing the requirements and releasing
directly from them. More commonly, if they even the product, the requirements inevitably change
get use cases, testers find that the pre-conditions a lot. On those projects that follow Company Z’s
and post-conditions are too sketchy to be useful, defined change management process, the testers
the steps in the use case are too high level, and are informed of every change to the
the expected results are not clearly defined. requirements and the changes are clearly
marked in the requirements documents. While
Another common problem is the lack of
this may mean a lot of test maintenance, at least
requirements tracing. The testers plan their test
the tests match the plan of record. But . . . for all
scenarios around the features and use cases. To
the other projects, reality looks more like this:
ensure that each test scenario covers all the
detailed requirements that are related to a • The tester is informed that something
feature or a use case, they must know what changed in the requirements, but cannot
those relationships are. Company Z suggests a easily identify the change. There is no
Traceability Matrix to show these relationships. revision history. There is no change tracking.
Unfortunately, analysts complete it for only The tester must resort to line-by-line
about 30% of the projects, by one estimate. Even comparisons which is made more difficult
when analysts do create a Traceability Matrix, when the SRS is presented as a spreadsheet
they often leave it incomplete and out of date. with row grouping.
Without such documentation, the testers have to
guess about these requirements relationships. • Or, the tester may not be informed of the
change. Sometimes this happens because the
The chaos of change. But suppose that a requirements analyst didn’t know about it
tester is so lucky as to get a requirements analyst either. Sometimes it happens because the
who engages him in requirements sessions, analyst forgot to tell the tester. Either way,
writes a thorough Vision document, writes great the first notice the tester receives may be a
detailed requirements and excellent use cases, “working as designed” response to a defect
and provides a complete Traceability Matrix. report for a failing test.

4. Can agile help? This litany of problems is just systems are large and complex and critical to the
one of the reasons that Company Z has begun to operation of the company. And many members
investigate making a transition to an iterative or of the technical teams have minimal experience
agile development model where shorter cycles with these systems.
will reduce the impact of changing requirements.
While they need the agility and speed that Or is iterative better? While agile
shorter cycles enable, the company recognizes development may not be the perfect fit for all of
that the change will not be easy. the projects at Company Z, most could benefit
from at least adopting a more iterative approach
According to the criteria suggested by Jennitta to development. They could develop the
Andrea for determining whether an organization products in a series of short iterations. They
is ready for an agile development model, could document the requirements one or two
Company Z is iterations in
definitely an advance. And
“ugly stepsister” Team they could freeze
Experience
(Andrea, 2005). LOW the requirements
The agile “glass for the current
System HIG LOW SME
slipper” does not H iteration while
Criticality Experience
fit. Applying the developers
LOW HIG Ideal
H HIG
Andrea’s project LOW 10H and testers
Company Z
factors map, the CO-LOCATED
complete that
Domain HIG 100
radar diagram Complexity H
Team Size iteration. This
for Company Z is would eliminate
not promising. DISTRIBUTED
Team
most of the
Proximity requirements
The subject change
matter experts
management issues. But what
(SMEs) at Company Z are Figure 1 Radar diagram for Company Z
about the problems with the
generally inexperienced at
requirements themselves?
specifying software
requirements and certainly have no experience
Requirements analysts to the rescue. The
expressing them in the form of functional tests.
requirements analysts at Company Z could
Its teams, which do not include the SMEs, tend
relieve most of the angst that plagues their
to be large and they are located in several states
testers by consistently applying the company’s
across the U.S. as well as abroad. Its software
current requirements standards.

5. 1. Include the testers in the requirements 1. Include a section which shows the business
gathering sessions. context of the use case.
2. Include the detailed requirements and
2. Write thorough business opportunity and present them in a nested structure that
problem statements in the Vision document. shows the stakeholder needs and features
they relate to. This would eliminate the need
3. Include plenty of information about the
for a separate Traceability Matrix. For
“why” when documenting stakeholder needs,
example:
features, and detailed requirements.
Stakeholder Need #171
4. Provide enough detail so that there is no Feature #85
ambiguity. This might include a description of Detailed Requirement #150
what the requirement means to the Detailed Requirement #151
customer, screen shots or report layouts,
Changing the software development life cycle
validation rules, security rules, audit rules,
and improving the requirements are probably
and success criteria (Miller, 2009).
not changes that Company Z would make just to
5. Make sure the requirements are testable. To benefit its testers. Most large companies don’t
be sure, try to imagine a test for the change until it hurts…bad enough. But market
requirement—or ask a tester! If you can’t pressures and a tough economy have made this
figure out how to test it, rewrite it. corporation realize that it must change in order
to produce the systems it needs to survive. An
6. Write thorough use cases, making sure that iterative life cycle and improved requirements
the preconditions, post-conditions, and all documentation are necessary to enable rapid
the steps are testable. and flexible development. Luckily for the testers,
these changes are just what they need as well.
7. And finally, document the tracing
relationships between the requirements.
Besides having the requirements analysts
follow its existing requirements standards,
Company Z could reduce its testing costs by
making a few improvements to these standards.
In particular, several of the testers encouraged
two changes to the Use Case Specification
standard:

6. AUTHOR BIO: Fran McKain is a senior requirements
analyst at Company Z. Her previous 20 years of software
test experience make her very aware of the things that
make life difficult for testers. Eight years as a project
manager gave her an appetite for solving such problems.
References
Andrea, J. ( 2005). If the shoe doesn’t fit: Agile
requirements for stepsister projects. Retrieved January
30, 2011 from www.stickyminds.com
Derfler, K. (2001). Should testing be involved in the
requirements elicitation process? Retrieved January 31,
2011 from www.stickyminds.com
Goodpasture, J. C. (2011). Enterprise agile and the business
analyst. Retrieved January 30, 2011 from
www.stickyminds.com
Miller, S. (2009). Reducing costs with good requirements
and code reviews. Retrieved January 31, 2011 from
www.stickyminds.com