agile document is
just barely good enough, or just barely
sufficient, for the situation at hand.
Documentation is an important part of
software development projects, but unlike
traditionalists who often see documentation as a
risk reduction strategy, agilists typically see
documentation as a strategy which increases
overall project risk and therefore strive to be
as efficient as possible when it comes to
documentation. Agilists write documentation when that's the best way to
achieve the relevant goals, but there often proves
to be better ways to achieve those goals than
writing static documentation. This article
summarizes common "best practices" which
agilists have adopted with respect to
for increasing the agility of documentation:
majority of the information captured in traditional
specification documents, such as requirements
specification, architecture specifications, or
design specifications, can be captured as "executable specifications" in the form
of tests. When you
take a Test-Driven Development (TDD) approach
With TDD you
write a test, either at the customer/acceptance
level or the developer level, before writing
sufficient functionality to fulfill that test.
The tests are used for two purposes: they
specify the requirements/architecture/design and
they validate your work. This is an example of
Single Source Information.
the agile strategy is to defer the creation of all documents as late
as possible, creating them just before you need
them via a practice called "document
example, system overviews are best written towards
the end of the development of a release because you
know what you’ve actually built. Similarly,
of user and
is also best
end of the
so that you
as there is
no need to
once it has
cost and the
will be out
If you write
then you are
at risk of
do not want
early in a
later in the
and when you
is that your
be a few
An extreme version of this practice is to wait until you are finished and then
write the documentation, the primary advantage being
that you are writing about a known and stable thing (the
release of the software that you just built).
There are clearly several disadvantages to this
have likely forgotten some of the reasons behind the
decisions that you made, clearly a problem if this is
- You may not have the right
people anymore to write the documentation because
- You may not
have funding to do the work.
- The will to write the
documentation may no longer exist.
modeling tools can reverse-engineer existing code
and present a multitude of views into it. In
short, you can save significant money by generating
the majority of the system documentation that you
but not Too Simple
not ensure project success, in fact, it
increases your chance of failure. Documentation
documentation. Follow the
Use the Simplest
Create Simple Content,
Depict Models Simply when creating
The best documentation is the simplest that
gets the job done.
Don’t create a fifty-page document when a
five page one will do.
Don’t create a five-page document when five
bullet points will do. Don’t create an elaborate and intricately detailed diagram
when a sketch will do.
Don’t repeat information found elsewhere
when a reference will do. Write in point form. Document
only enough to provide a useful context. Start with
a document that's minimal enough for the needs of
its customers then augment it as needed.
To determine what is truly the minimum amount
of documentation required by my customers I will
actively explore how they intend to use the
documentation and why they are using it that way.
The basic trade-off is the "security" of
having the document against your trust in its accuracy.
What would you rather have, 500-page system document
that is likely to have a significant number of errors in
it but significant details or a 10-page, high-level
overview? The large document would very likely
have most of the information that you need to maintain
and enhance your system, but would you trust the
information contained in it? The shorter document
very likely wouldn't contain the detailed information
you need but it would provide a map from where you could
dive into the source code, or other documents, for
details. You'd be more likely to trust this document
because it's shorter, worst case you could easily update
or simply rewrite it if you found it to be grossly
inaccurate, and because it deals with high-level
concepts such as your system architecture which will
change more slowly than the detailed minutiae contained
in the larger document. It is important to understand
that I am not saying that a larger document is
automatically of lower quality than a shorter one, but I
am saying that it is likely to be perceived as such
until proven otherwise.
travel as light as you possibly can,
barely good enough to fulfill it's purpose. One way to achieve this is to build larger
documents from smaller ones.
For example, I once worked on a project where
all documentation was written as HTML pages, with
each page focusing on a single topic. Agile teams
often use Wikis like this. One page described the user interface architecture for our
system, a page which included a user interface flow
diagram and appropriate text describing it.
The table of contents pages for the system
documentation and the support guide both linked to
this UI architecture page.
The advantage was that this information was
defined in one place and one place only, so there
was no opportunity for overlap.
2.3 Put the
Information in the
Where will somebody likely want a piece of
Is that design decision best documented in
the code, added as note on a diagram, or best placed
in an external document?
part of a
use case, in
or as an
test? The answer to these sorts
of question should be driven
by the needs of the customer of that information,
where are they most likely to need that information. It is also driven by your desire to follow the principle
Work – you should strive to record the information
it enhances your work the most (e.g.
Single Source Information).
You should also consider issues such as
indexing, linking, and accessibility when writing
documentation because you don’t always know who
will eventually become its customer.
models are displayed publicly – on a
whiteboard, corkboard, or internal web site – you
are promoting transfer of information and thus
communication through the application of what
Cockburn refers to as an “information
radiator”. The greater the communication on your
project the less need for detailed documentation
because people already know what you’re doing.
Having said that, don’t forget to indicate
the status of your work so that people can put
them in context – you’ll treat a model that is
still a draft much different than one that has been
baselined for your current release of software.
You should only create a document if it fulfills a clear,
important, and immediate goal of your overall
Don’t forget that this purpose may be short
term or long term, it may directly support software
development efforts or it may not. Also
that each system has its own unique documentation
needs, that one size does not fit all -- the implication
going to be
same set of
least not if
You want to
work closely with the audience of the document so that you know what they actually require of it.
To do this
you need to
identify who the potential customer(s) for your documentation
are, what they believe they require, and then
negotiate with them the minimal subset that they
actually need. To discover what they believe they
require ask them what they do, how they do it, and
how they want to work with the documentation
that you are to produce.
By understanding the needs of your customers
you will be able to deliver succinct and sufficient
documentation and deliver it where they will
actually need it and find it – it doesn’t matter
how well written a document is if nobody knows that
Years ago I worked for a large Canadian
financial institution and one of their policies were
that you couldn’t transition a system to someone
else until they were willing to accept it.
They would inspect your code and supporting
artifacts and if they felt the artifacts weren’t
up to par then you needed to improve it and try
you would work on improving the artifacts together,
and sometimes not.
This practice provided a fair and effective
quality gate between developers and the customers of
our work. As
writer of the documentation it is your job to ensure
that it has true meaning and provides value, your
customer’s role is to validate that you have done
end of the
When you do
you should take an evolutionary (iterative and incremental) approach to its development so that you gain feedback as to its actual value.
words, write a little bit, show it to someone, get
feedback, act on that feedback, and then iterate.
The best documents are written iterative, not all at
once. An iterative approach enables you to
home in on what the audience for your documentation
Highsmith believes that the
one of understanding, not of documentation,
therefore you should not overrate the value of
Well-written documentation supports
organizational memory effectively, but is a poor
way to communicate during a project. Your goal is to ensure that maintenance
developers understand how the system works so they
can evolve it over time, not to produce a mound of
documentation that they may or may not use.
Your goal is to ensure that your users work
with your system effectively, not that they have a
pretty help system available to them.
Your goal is to enable your support and
operations staff, not bury them with paper.
Documentation supports knowledge transfer,
but it is only one of several options available to
you and as Figure 2 depicts it often isn’t the best option. The
desirable one. Conversations with project stakeholders,
having them actively involved with development,
being available to work through any issues with them
often go much further than the best documentation.
Documentation becomes a better option for you
the greater the distance, either physical or
temporal, between the individuals who are
how to do
take all of
the joy out
be for an
as an IT
that developers rarely trust the documentation, particularly
detailed documentation because it's usually out of
sync with the code, so minimize the amount of
that you do
If you’ve chosen to keep your
deployment diagram, your
user interface flow
diagram, and your
physical data diagram up to date
throughout development then that is a good sign that
these are valuable models that you should base your
Models that weren’t kept up to date likely
weren’t because there was little sense in doing
so, so not only are they out of date they aren’t
of value anyway.
In this respect documents are just
like models, my recommendation is to follow the practice
Update Only When It Hurts.
Agile documents, like agile models, should be just good
times a document can be out of date and it doesn’t
matter very much. For example, when I wrote the first version of this article I
was working with
the early release of the JDK v1.3.1 yet I regularly used
reference manuals for JDK 1.2.x – it’s not a perfect
situation but I get by without too much grief because
the manuals I’m using are still good enough. Would the manuals for Java v1.0.x be sufficient?
Likely not, because there has been a significant
change since that release and my productivity loss would
be much greater than the cost of new manuals.
help you to
is to treat
it should be
put on your
The need to
clearly is a
the need to
you make in
made in new
to how much
you make its
the investment in documentation is a
business decision, not a technical one: you shouldn't
work as a
Does the person know what they're asking for,
and why they need it, or are they asking for it
because they've been told to ask for it? Are
users asking for documentation because they were
burned in the past by developers, or their
colleagues were burned in the past, and now they ask
for everything in the hopes they'll get something?
Does the requester understand the trade-offs that
are being made, see What Are The
Issues Associated with Documentation?, and that
comes at a
is that when
there is an
ask are what
to use the
for and how
When you do
there as a
way ways to
You should understand the total cost of ownership (TCO)
for a document, and strive to
maximize stakeholder ROI to provide the best value possible to your
Someone must explicitly choose to make the investment in
The benefit of having documentation must be
greater than the cost of creating and maintaining it.
- Ask whether you NEED the documentation, not
whether you want it.
Some important observations:
Documentation is as much a part of the system as
the source code. In addition to working
software, you'll also likely need to minimally
deliver user manuals, support documentation,
operations documentation, and system overview
primary goal is to develop
secondary goal is to enable your next
effort. Yes, building high-quality working
software which meets the needs of your stakeholders
is important, but ensuring that the people who come
after you can maintain and enhance it, operate it,
and support it is also important.
- Documentation still serves a purpose.
In particular, you want to capture high-level information in documentation
but not details. You will still need to
capture important information permanently, and
sometimes regulations require certain levels of
documentation (yet another
- Agilists are in fact writing documentation.
were just as
and so on.
to lay waste
to some of
have when it
Figure 4. Deliverable documentation creation.
writers bring a lot to the table when it comes time
to write documentation because they know how to
organize and present information effectively. Don’t have access to a technical writer?
- Consider reading and following the advice
presented in UnTechnical Writing
or taking a night-school course in writing
- Try writing documentation with a partner, just like
there is significant value pair programming
there is similar value in “pair documenting”.
Have shared ownership of all documentation so that multiple people will work on it.
text-to-speech software that allows you to listen to
what you’ve written, a great way to discover
poorly written passages.
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
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.
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.