 |
If your goal is to have
potentially shippable software every sprint as
they say in
Scrum, or better yet to have
a potentially consumable solution every
iteration as we say in
Disciplined Agile Delivery (DAD),
then you will need to keep your deliverable
documentation in sync with your
software/solution -- in other words, write
deliverable documentation continuously
throughout the project. Your other option
is to leave the finalization of your deliverable
documentation to the end of the project, to
document late. |
|
I've been
using the
term
"deliverable
documentation",
but what
does that
mean?
Deliverable
documentation
is the
documentation
that you
need to
deliver to
your
stakeholders
as part of
your overall
solution.
This will of
course vary
between
projects,
but
deliverable
documentation
typically
includes
user
manuals,
training
materials,
operations
manuals,
support
manuals, and
system
overviews.
It typically
does not
include
requirements
specifications
or design
specifications,
except of
course in
regulatory
situations
where such
documentation
is required
or in
contract
negotiations
where it's
required as
part of the
contract.
Of course,
with all
such
artifacts, I
highly
suggest
following
the best
practices of
agile
documentation.
Here are
some good
heuristics
to document
continuously
in an
effective
manner:
-
Wait for
the
information
to
stabilize. Write the
documentation
after you've
done the
majority
of the
development
work, in
other
words
towards the
end of the
iteration.
If you
document
information
that
isn't
yet
stable,
you run
the risk
of
having
to
rework
your
documentation.
-
Write documentation
during the
iteration
with
long
iterations.
With
"long"
iterations,
say four
weeks or
more,
you have
sufficient
time for
information
to
stabilize
and
thereby
capture
it
during
that
iteration.
-
Write
documentation
the
following
iteration
with
short
iterations.
With
"short"
iterations,
two
weeks or
less,
it's
unlikely
that the
information
will
stabilize
in time
for you
to
complete
the
documentation.
To
remain
efficient
as
possible
you
should
consider
writing
the
deliverable
documentation
for
iteration
N during
iteration
N+1.
With medium
length
iterations
(two to
four
weeks)
you will
need to
experiment
to identify
which
approach
works better
for you.
Note that
with this
practice
many teams
will include
criteria
around
updating
deliverable
documentation
in their
definition
of done for
the
iteration.
In other
words,
documentation
becomes part
of the
acceptance
criteria for
determining
whether a
work item
(such as a
user story
or defect
report) has
been fully
implemented.
This
reflects the
Disciplined
Agile
Delivery
(DAD)
philosophy
of
solutions
over
software.
Risk
Profile of
this
Practice
|
By writing
deliverable
documentation
continuously
throughout
the project,
you address
the
following
risks:
-
Delivery
risk.
By
writing
the
documentation
in sync
with the
rest of
the
solution,
you know
you have
sufficient
documentation
to
support
what
you've
built to
date.
The
implication
is that
your
solution
will in
fact be
potentially
shippable
at the
end of
each
iteration.
-
Accuracy
risk.
Because
the
feedback
cycle
between
doing
the work
and
documenting
what you
did is
short it
is much
more
likely
that you
will
remember
the
critical
details
which
need to
be
captured.
However,
there
are
three
risks
which
are
potentially
increased
by
this
practice:
-
Financial
risk.
Because
the
requirements
are
likely
to
evolve
throughout
the
project,
you will
need to
update
the
deliverable
documentation
to
reflect
those
changes.
You are
in
effect
"travelling
heavy"
from an
agile
point of
view by
documenting
continuously.
-
Schedule risk.
It takes
time and
effort
to write
and
maintain
this
documentation,
and any
rework
of the
documentation
resulting
from
evolving
requirements
in
effect
impacts
your
schedule
due to
the
required
rework.
-
Accuracy
risk.
Sadly,
it's
easier
to write
about
documenting
continuously
than it
is to do
it.
It's
common
that
agile
teams
will put
off
writing
documentation
until
they
have
time to
do so,
in
effect
moving
towards
the
document
late
practice
instead
of this
one.
|
 |
 |
|
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. |
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.


|