 |
A common agile practice is to defer the creation of all documents as late
as possible, creating them just before you need
them. For
example, system overviews are best written towards
the end of the development of a release because you
know what you’ve actually built. Similarly,
the majority
of user and
support
documentation
is also best
written
towards the
end of the
lifecycle.
Figure
1
compares the traditional and agile approaches to
documentation, showing the relative total amount
of effort invested in creating and maintaining
documentation throughout the
SDLC. Fundamentally,
the strategy is to wait until the information
has stabilized before you capture it in
documentation. It is risky to capture
speculative information, such as requirements or
design details, early in the lifecycle because
those details are likely to change. |
|
Figure 1.
Documentation
throughout
the software
development
lifecycle.

It's
interesting
to note the
differences
in the two
strategies:
-
Agilists
model
and plan
early in
the
project,
but they
don't
write
detailed
documents.
Agilists
will
invest a
bit of
time at
the
beginning
of the
project
to
envision
the
initial
requirements
and the
initial
architecture.
They do
this
because
people
will ask
questions
such as
what are
you
going to
do, how
much
will it
cost,
how long
will it
take,
and how
are you
going to
build
it.
The
implication
is that
you need
to do
some
high-level
requirements
and
architecture
modeling,
but that
doesn't
mean
that you
need to
write
mounds
of
detailed
specifications.
Get the
value
out of
modeling,
which is
to think
things
through,
without
the cost
of
needless
documentation.
Agilists
will
also
create a
high-level
plan
showing
projected
delivery
dates,
major
dependencies,
and so
on.
-
Agilists
still
create
detailed
specifications.
Agilists
capture
the
details
on a
just-in-time
(JIT)
basis,
not up
front.
They
also
prefer
to write
executable specifications
in the
form of
tests,
not
static
documents.
When you
take a
Test-Driven
Development
(TDD)
approach
this is
quite
easy to
achieve.
In the
end,
Agilists
often do
more
specification
than
traditionalists
but we
do it in
a
different
manner.
-
Agilists
still
write
supporting
documents.
Supporting
documentation,
such as
user
manuals,
operations
manuals,
and
support
manuals,
are an
important
deliverable
of any
system
development
project.
Agilists,
like
traditionalists,
will
write
these
documents
towards
the end
of the
lifecycle
once the
system
has
stabilized.
However,
because
Agilists
treat
documentation
like a
requirement
we will
estimate
the
effort
to write
it and
ask our
stakeholders
to
prioritize
it along
with all
other
requirements.
Because
of this
greater
level of
stakeholder
participation
and
control
Agilists
will
tend to
be more
efficient
than
traditionalists
when it
comes to
that
sort of
documentation
(when
you put
a
visible
price
tag on
things
people
get
really
smart
really
fast
over how
they
invest
their
money).
-
Agilists
still
write
system
overview
documentation.
There
will
still be
some
need for
high-level
overview
documentation
for the
people
who will
need to
maintain
the
system.
However,
because
Agilists
write
high-quality
code
than
traditionalists
and have
a
regression
test-suite
for
their
code
(which
in
effect
is the
detailed
specifications
for the
system)
you will
find
that you
only
need a
concise
overview
consisting
mainly
of
critical
high-level
diagrams.
The
greater
discipline
of
Agilists,
and the
resulting
higher
levels
of
quality,
result
in less
need for
detailed
documents
(which
are
invariably
out of
date
anyway,
further
contributing
to the
quality
challenges
on
traditional
projects).
-
Agilists
have a
lower
cost
curve.
Not only
is the
agile
curve in
Figure 1
lower,
it is
also
less
steep.
By
documenting
early in
the
lifecycle
traditionalists
incur
increased
documentation
maintenance
costs
throughout
the
lifecycle.
By
waiting to
document
information
once it has
stabilized
you reduce
both the
cost and
several
risks
associated
with
documentation:
-
Financial
risk.
Cost is
reduced
because you
won't waste
time
documenting
information
that
changes,
which in
turn
motivates
you to
update the
documentation.
If you
write
documentation
containing
information
which
has not
yet
stabilized
then you
are at
risk of
having
to
rework
the
documentation
once the
information
has
changed.
In other
words,
you do
not want
to
invest
much
time
documenting
speculative
ideas
such as
the
requirements
or
design
early in
a
project.
Instead,
wait
until
later in
the
lifecycle
when the
information
has
stabilized
and when
you know
what
information
is
actually
useful
to you.
The
implication
is that
your
documentation
effort
may be a
few
iterations
behind
your
software
development
effort.
-
Accuracy
risk.
Accuracy is
improved
because
there is
significantly
less
chance
that
your
existing
documentation
will be
out of
date.
However,
this doesn't
mean that
all
documentation
should be
left towards
the end
because
there some
risks are
increased:
-
Completion
risk.
You may
not
complete
the
required
documentation
due to
lack of
resources
(financial,
time). To
counteract
this
risk
make the
creation
of those
documents
explicit
requirements
which
should
be
prioritized
and
estimated
like any
other
requirement.
-
Accuracy
risk.
You may
forget
some
information.
To
counteract
this
risk you might
still want
to take
notes for
these sorts
of documents
throughout
development
so that you
don't lose
critical
information.
These notes
may be
nothing more
than
point-form
information
as there is
no need to
"polish"
documents
until just
before final
delivery of
them.
 |
|
Agile Documentation describes a collection of
patterns for writing effective system documentation. |
 |
|
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
of the
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
such as
refactoring and
test-driven development
(TDD). The Object Primer also includes a
chapter overviewing the critical database
development techniques (database refactoring,
object/relational mapping,
legacy analysis, and
database access coding) from my award-winning
Agile Database Techniques
book. |
 |
|
Agile Modeling: Effective Practices for Extreme
Programming and the Unified Process is the seminal
book describing how agile software developers approach
modeling and
documentation. It describes principles and
practices which you can tailor into your existing
software process, such as
XP, the
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
elicit requirements,
architect, and then
design your system in an agile manner. |
I actively work with clients around the world to
improve their information technology (IT) practices as
both a mentor/coach and trainer. A full description of
what I do, and how to contact me, can be
found here.
|