To be honest, I'm not very enamored with the term
"best practice". I believe that the term
"contextual practice" makes far more sense because what
is a "best practice" in some situations proves to be a
"worst practice" in others. Having said that,
people are interested in best practices so here they are
when it comes to agile requirements modeling:
Stakeholders actively participate
Adopt inclusive models
Take a breadth-first
Model storm details
just in time (JIT)
Treat requirements like
a prioritized stack
Prefer executable requirements over static
Your goal is to
implement requirements, not document them
you have a wide range of stakeholders
platform independent requirements to a point
Smaller is better
stakeholders into developers
When you are requirements modeling
the critical practice is Active Stakeholder
There are two issues that need to be addressed to
enable this practice – availability of project
stakeholders to provide requirements and their (and
your) willingness to actively model together.
My experience is that when a project team
doesn’t have adequate access to project stakeholders
that this is by choice. You have funding for your project, don’t you?
That must have come from some form of project
stakeholder, so they clearly exist.
Users must also exist, or at least potential
users if you’re building a system you intend to
provide to the public, so there clearly is someone that
you could talk to.
Yes, it may be difficult to find these people.
Yes, it may be difficult to get them to
with it. In
Requirements Challenges I discuss several common
problems that development teams often face, including
not having full access to project stakeholders.
My philosophy is that if your project
stakeholders are unable or unwilling to participate then
that is a clear indication that your project does not
have the internal support that it needs to succeed,
therefore you should either address the problem or
cancel your project to minimize your losses.
Active Stakeholder Participation
is a core practice of Agile Modeling (AM).
does it mean for a project stakeholder to actively
participate? Figure 1 presents a
high-level view of the requirements process, using the
UML activity diagrams, indicating the tasks
that developers and project stakeholders are involved
with. The dashed line is used to separate the effort
into swim lanes that indicate what role is responsible
for each process. In this case you see that both project
stakeholders and developers are involved with
identifying ideas or suggestions, discussing a potential
requirement, and then modeling and potentially
documenting it. Project stakeholders are solely responsible for
prioritizing requirements, the system is being built for
them therefore they are the ones that should set the
priorities. Likewise, developers are responsible for
estimating the effort to implement a requirement because
they are the ones that will be doing the actual work –
it isn’t fair, nor advisable, to impose external
estimates on developers. Although prioritization and estimation of
requirements is outside the scope of AM, it is however
within the scope of the underlying process such as XP or
UP that you are applying AM within, it is important to
understand that these tasks are critical aspects of your
overall requirements engineering effort. For
further reading, see the
Agile Requirements Change
A UML activity diagram overviewing the requirements
My philosophy is that project
stakeholders should be involved with modeling and
documenting their requirements, not only do they provide
information but they actively do the work as well.
Yes, this requires some training, mentoring, and
coaching by developers but it is possible.
I have seen project stakeholders model and
document their requirements quite effectively in small
start-up firms, large corporations, and government
seen it in the telecommunications industry, in the
financial industry, in manufacturing, and in the
is this important?
Because your project stakeholders are the
They are the ones that know what they want and they can be taught how to model and document
requirements if you choose to do so.
This makes sense from an agile point of view
because it distributes the modeling effort to more
To make it easier for project
stakeholders to be actively involved with requirements
modeling and documentation, to reduce the barriers to
entry in business parlance, you want to follow the
practice Use the Simplest Tools.
Many of the requirements artifacts listed in Table
1 below can be modeled using either simple or
complex tools – a column is included to list a simple
tool for each artifact.
Figure 2 and Figure
3 present two
inclusive models created using simple tools,
Post It notes and flip chart paper was used to model the
requirements for a screen/page in Figure
essential UI prototype) and index cards were used for conceptual modeling
in Figure 3 (a
CRC model). Whenever you bring technology into the
requirements modeling effort, such as a drawing tool to
create “clean” versions of use case diagrams or a
full-fledged CASE tool, you make it harder for your
project stakeholders to participate because they now
need to not only learn the modeling techniques but also
the modeling tools.
By keeping it simply you encourage participation
and thus increase the chances of effective
An essential user interface prototype.
Two CRC cards.
in the same
itself in a
will need to
My experience is that
it is better to paint a
wide swath at first, to try
to get a feel for the bigger picture, than it is to
narrowly focus on one small aspect of your system.
By taking a breadth-first approach you
quickly gain an overall understanding of your system
and can still dive into the details when
Many organizations prefer a "big
modeling up front (BMUF)" approach to modeling where
you invest significant time gathering and documenting
requirements early in the project, review the
requirements, accept and then baseline them before
implementation commences. This sounds like a great
idea, in theory, but the reality is that this approach
is spectacularly ineffective. A 2001 study
performed by M. Thomas in the U.K. of 1,027 projects
showed that scope management related to attempting
waterfall practices, including detailed, up-front
requirements, was cited by 82 percent of failed projects
as the number one cause of failure. This is backed
up by other research – according to Jim Johnson of the
Standish Group when requirements are specified early in
the lifecycle that 80% of the functionality is
relatively unwanted by the users. He
reports that 45% of features are never used, 19% are
rarely used, and 16% are sometimes used. Why does
this happen? Two reasons:
When project stakeholders are
told that they need to get all of their requirements
down on paper early in the project, they desperately
try to define as many potential requirements (things
they might need but really aren't sure about right
now) as they can. They know if they don't do
it now then it will be too hard to get them added
later because of the
change management/prevention process which will
be put in place once the requirements document is
Things change between the time
the requirements are defined and when the software
is actually delivered.
The point is that you can do a
little bit of initial, high-level
up front early in the project to understand the overall
scope of your system without having to invest in mounds
Through initial, high-level modeling you can gain the knowledge that you need to guide the project but choose to wait to act on it.
Requirements are identified throughout most of your project.
Although the majority of your requirements
efforts are performed at the beginning your project
it is very likely that you will still be working
them just before you final code freeze before
Embrace Change. Agilists take an evolutionary,
iterative and incremental, approach to development.
The implication is that you need to gather requirements
in exactly the same manner. Luckily AM includes
practices such as
Create Several Models in Parallel,
Iterate To Another Artifact, and
Model In Small Increments which enable evolutionary
The shorter the feedback cycle between model storming a requirement and implementing it, the less need there is for documenting the details.
4 overviews the
approach to managing
requirements, reflecting both
Extreme Programming (XP)’s
planning game and the
Scrum methodology. Your
software development team has a
estimated requirements which needs to be
implemented – co-located agile
teams will often
literally have a stack of user
stories written on index
cards. The team takes the
highest priority requirements
from the top of the stack which
they believe they can implement
within the current iteration.
Scrum suggests that you freeze
the requirements for the current
iteration to provide a level of
stability for the developers.
If you do this then any change
to a requirement you’re
currently implementing should be
treated as just another new
to note that
to take a
instead of a
you see in
Figure 5. Lean work
During development it is quite common
to model storm for several
minutes and then code, following common Agile practices
Test-First Design (TFD) and
for several hours and even several days at a time to
implement what you've just modeled. This is where
your team will spend the majority of its time. Agile teams do the
majority of their detailed modeling in the form of
executable specifications, often
customer tests or development tests. Why
does this work? Because your model storming efforts
enable you to think through larger, cross-entity issues
whereas with TDD you think through very focused issues
typically pertinent to a single entity at a time. With refactoring you evolve your design via small steps to
ensure that your work remains of high quality.
of as a
7. Your Goal is To Effectively
Not Document Them
Too many projects are
crushed by the overhead required to develop and
maintain comprehensive documentation and
traceability between it. Take an
agile approach to documentation and keep it lean
and effective. The most effective
just barely good enough for the job at hand.
By doing this, you can focus more of your energy on
building working software, and isn't that what you're
really being paid to do?
The urge to write requirements documentation should be transformed into an urge to instead collaborate closely with your stakeholders and then create a consumable solution based on what they tell you.
include managers of users, senior managers, operations staff
members, the "gold owner" who funds the project, support (help desk) staff members,
auditors, your program/portfolio manager, developers
working on other systems that integrate or interact with
the one under development, or maintenance professionals
potentially affected by the development and/or
deployment of a software project.
To name a
of what they
for what the
to need to
and then act
they go to
well for the
I’m a firm believer that
requirements should be technology independent.
I cringe when I hear terms such as
object-oriented (OO) requirements, structured
requirements, or component-based requirements.
The terms OO, structured, and component-based are
all categories of implementation technologies, and
although you may choose to constrain yourself to
technology that falls within one of those categories the
bottom line is that you should just be concerned about
it, just requirements.
All of the techniques that I describe below can
be used to model the requirements for a system using any
one (or more) of these categories.
However, I also cringe when I hear about people talk
about Platform Independent Models (PIMs), part of the
Model Driven Architecture (MDA) vision from the
Object Management Group (OMG). Few organizations
are ready for the MDA, so my advice is to not let
the MDA foolishness distract you from becoming effective
at requirements modeling.
Sometimes you must go away from the
ideal of identifying technology-independent
requirements. For example, a common constraint for
most projects is to take advantage of the existing
technical infrastructure wherever possible. At
this level the requirement is still technology
independent, but if you drill down into it to start
listing the components of the existing infrastructure,
such as your Sybase vX.Y.Z database or then need to
integrate with a given module of SAP R/3, then you've
crossed the line. This is okay as long as you know
that you are doing so and don't do so very often.
to think small. Smaller requirements, such as features and user stories, are
much easier to
estimate and to build to than are larger
requirements, such as use cases. An average use case describes greater
functionality than the average user story and is thus
considered “larger”. They're also easier to
prioritize and therefore
Think very carefully before
investing in a requirements traceability matrix, or in
full lifecycle traceability in general, where the
traceability information is manually maintained.
Traceability is the ability to relate aspects of project
artifacts to one another, and a requirements
traceability matrix is the artifact that is often
created to record these relations – it starts with
your individual requirements and traces them through any
analysis models, architecture models, design models,
source code, or test cases that you maintain.
My experience is that organizations with
traceability cultures will often choose to update
artifacts regularly, ignoring the practice
Only When it Hurts, so as to achieve consistency
between the artifacts (including the matrix) that they
also have a tendency to capture the same information in
several places, often because they employ overly
specialized people who "hand off" artifacts to other
specialists in a well-defined, Tayloristic process.
This is not traveling light.
Often a better approach is to
single source information and to build teams of
The benefits of having such a matrix is that it
makes it easier to perform an impact analysis pertaining
to a changed requirement because you know what aspects
of your system will be potentially affected by the
in simple situations (e.g with small co-located teams
addressing a fairly straightforward situation) when you have one or more people familiar with the system,
then it is much
easier and cheaper to simply ask them to estimate the
Furthermore, if a continuous integration strategy is in
place it may be simple enough to make the change and see
what you broke, if anything, by rebuilding the system.
In simple situations, which many agile teams find
themselves in, my
experience is that traceability matrices are highly
overrated because the total cost of ownership (TCO) to maintain such matrices,
even if you have specific tools to do so, far outweigh
Make your project stakeholders aware of the real
costs and benefits and let them decide – after all, a
traceability matrix is effectively a document and is
therefore a business decision to be made by them.
If you accept the AM principle
Maximize Stakeholder ROI, if you're honest about the
TCO of traceability matrices, then they often prove to
answer is in
and when you
will automatically provide most of your traceability
needs as a side effect of normal development activities.
do a bit
CFR 21 Part
you need to
In short, I question
gist of it),
to do, and
about it. In
It's requirements analysis,
not retentive analysis. ;-)
Everyone should have a basic understanding of
a modeling technique, including your project
never seen CRC cards before?
Take a few minutes to explain what they are,
why you are using them, and how to create them.
You cannot follow the practice
Stakeholder Participation if your stakeholders are
unable to work with the appropriate modeling
Do not force artificial, technical jargon
onto your project stakeholders.
They are the ones that the system is being
built for, therefore, it is their terminology that
you should use to model the system.
Constantine and Lockwood say, avoid
geek-speak. An important artifact on many
projects is a
concise glossary of business terms.
doesn’t have to be an arduous task.
In fact, you can always have fun doing it.
Tell a few jokes, and keep your modeling
People will have a better time and will be
more productive in a “fun” environment.
Investing the effort to model requirements,
and in particular applying
agile usage-centered design
techniques, are new
concepts to many organizations.
An important issue is that your project
stakeholders are actively involved in the modeling
effort, a fundamental culture change for most
organizations. As with any culture change, without the support of senior
management you likely will not be successful.
You will need support from both the managers
within you IS (information system) department and
within the user area.
An implication of this approach is that your project
stakeholders are learning fundamental development
skills when they are actively involved with a
It is quite common to see users make the jump
from the business world to the technical world by
first becoming a
business analyst and then learning
further development skills to eventually become a
My expectation is that because agile software
development efforts have a greater emphasis on
stakeholder involvement than previous software
development philosophies we will see this phenomena
occur more often – keep a look out for people
wishing to make this transition and help to nurture
their budding development skills. You never know, maybe some day someone will help nurture your
business skills and help you to make the jump out of
the technical world.
The Object Primer 3rd Edition: Agile Model Driven
Development with UML 2 is an
important reference book for agile modelers,
describing how to develop 35
types of agile
models including all 13
UML 2 diagrams.
Furthermore, this book describes the techniques
Full Lifecycle Object Oriented Testing
(FLOOT) methodology to give you the fundamental
testing skills which you require to succeed at
agile software development. The book also
shows how to move from your agile models to
source code (Java examples are provided) as well
as how to succeed at implementation techniques
(TDD). The Object Primer also includes a
chapter overviewing the critical database
development techniques (database refactoring,
legacy analysis, and
database access coding) from my award-winning
Agile Database Techniques
Agile Modeling: Effective Practices for Extreme
Programming and the Unified Process is the seminal
book describing how agile software developers approach
documentation. It describes principles and
practices which you can tailor into your existing
software process, such as
Rational Unified Process (RUP), or the
Agile Unified Process (AUP), to streamline your
modeling and documentation efforts. Modeling and
documentation are important aspects of any software
project, including agile projects, and this book
describes in detail how to
architect, and then
design your system in an agile manner.
The Elements of UML 2.0 Style describes a collection
of standards, conventions, and
for creating effective
UML diagrams. They are based on sound, proven
software engineering principles that lead to diagrams
that are easier to understand and work with. These
conventions exist as a collection of simple, concise
guidelines that if applied consistently, represent an
important first step in increasing your productivity as
a modeler. This book is oriented towards
intermediate to advanced UML modelers, although there
are numerous examples throughout the book it would not
be a good way to learn the UML (instead, consider
The Object Primer). The book is a brief 188
pages long and is conveniently pocket-sized so it's easy
to carry around.
We actively work with clients around the world to
improve their information technology (IT) practices,
typically in the role of mentor/coach, team lead, or trainer. A full
description of what we do, and how to contact us, can be
found at Scott W.
Ambler + Associates.