Software developers often see documentation as a scourge, an unnecessary burden
that must be borne in order to deliver a system. In my experience, however,
documentation doesn't have to be dysfunctional. In fact, documentation can be
quite effective and arguably agile in its applicationif you choose to
make it so. Here are 12 steps you can take to ensure your documentation is agile:
Focus on the customer. Identify who will use your documentation and what
they believe they require. Then negotiate with them to determine the minimal
subset that they actually need.
The customer determines sufficiency. As the documentation's author, you
should ensure that it has meaning and provides value; your customer's role
is to validate that you have done so.
Document with a purpose. Create a document only if it fulfills a clear,
important and immediate goal of your overall project.
Prefer other forms of communication over documentation. Documentation supports
knowledge transfer, but it's only one of several methods of communication.
Often, alternative options may be more useful.
Put documentation in the most appropriate place. Where will someone want
a piece of documentation? Varying projects require different types of documentation.
For example, a design decision is best documented in the code when programmers
are the primary audience, is best added as a note on a diagram when the primary
audience is a designer, or is best placed in an external document when the
audience includes management.
Wait for what you are documenting to stabilize. Delay the creation of all
documents as long as possible, creating them just before you need them. For
example, system overviews are best written as you near a product's release,
because by that time, you know what you've actually built.
Display models publicly. When you publicly display modelson a whiteboard,
corkboard or internal Web siteyou're promoting transfer of information
and communication. More communication leads to less detailed documentation,
because people are already aware of the basic information they've gleaned
from your model.
Document current models first. If you keep a model up-to-date, it's probably
valuableand therefore worthy of documentation.
Require people to justify documentation requests. Ask your customers what
they intend to use the documentation for and how they will actually use it.
Their answers will often reveal that some documentation functions only as
a security blanket. There are much better way ways to address fear than by
providing superfluous documentation.
Write the fewest documents with the least overlap. Try to build larger documents
from smaller ones. I once worked on a project in which all documentation was
written as HTML pages, with each page focusing on a single topic. This process
defined information in one place and one place only, so there was no opportunity
Get help from an experienced writer. Technical writers know how to organize
and present information effectively. Also, write documentation with a partnerjust
as pair programming can provide significant value ( http://pairprogramming.com
), "pair documenting" can be equally effective.
Recent Discussions on the Agile Modeling Mailing List:
Whither Object Constraint Language (OCL)?
The Object Management Group (OMG), http://www.omg.org , promotes OCL as a simple,
formal language to be used in conjunction with its Unified Modeling Language
(UML). First introduced in the mid-1990s, the OCL has been all but ignored by
the software development industry. Consensus on the mailing list is that, currently,
there is a severe lack of tool support for OCL, the language isn't readable
by project stakeholders and is therefore inappropriate for requirements specification,
and developers are more motivated to learn programming languages such as Java
and C# instead of formal languages such as OCL, Z or VDM++. My January
2002 column in Software Development will explore OCL in greater detail.
Big Design Up Front (BDUF) vs. Emergent Design
Do you invest the time up-front to create a detailed model before you build
something, or do you iteratively model, code and test your application in an
incremental manner, allowing your design to emerge over time? This is clearly
one of the fundamental "religious issues" within the modeling community,
and the debate still rages on the AM mailing list. Do you make the fundamental
trade-off of accepting the risk of modeling something that's more robust than
you currently need, thereby incurring the expense of overbuilding your software?
Or do you trust that you can refactor your software when you need to support
new requirements as they arise? Both approaches have their risks and rewardswhich
do you prefer?
A thread that spun off from the BDUF discussion focused on the difficulty of
refactoring persistence-related items like the physical schema of a database.
Relational databases are often highly coupled, both internally (through stored
procedures, indices and foreign keys) and externally (to application software).
This high degree of coupling, along with the poor encapsulation typical of most
databases, makes them difficult to refactor, because one small change to your
database can ripple through dozens of applications. Our discussion focused on
the issues pertaining to refactoring persistence as well as techniques to make
this effort easier. We discussed the use of a persistence framework/layer, effective
mapping strategies, effective data conversion strategies and ways for developers
and DBAs to work together.
The September 11th Fund of the United Way
I'll give two online presentations about Agile Modeling on Friday, November
30th. The cost is $25, and all proceeds will be donated to the United Way's
September 11th Fund. For details, visit http://www.agilemodeling.com/training.htmhope
you decide to get involved.
Agile Documentation http://www.agilemodeling.com/essays/agileDocumentation.htm
This essay explores critical issues in effective document creation, including
valid and invalid reasons for creating documentation, what "agile documentation"
and "traveling light" really mean, and how can you make this advice
work for you in practice.
Alistair Cockburn's Home Page http://members.aol.com/acockburn/
Alistair provides insights into issues such as communication, agile software
development and software process improvement. You can also download a PDF draft
of his latest book.
Mapping Objects to Relational Databases http://www.ambysoft.com/mappingObjects.html
This paper describes techniques for using objects and relational databases together,
exploring some of the issues that make persistence refactoring of relational
Currently we allow the following HTML tags in comments:
These tags can be used alone and don't need an ending tag.
<br> Defines a single line break
<hr> Defines a horizontal line
These require an ending tag - e.g. <i>italic text</i>
<a> Defines an anchor
<b> Defines bold text
<big> Defines big text
<blockquote> Defines a long quotation
<caption> Defines a table caption
<cite> Defines a citation
<code> Defines computer code text
<em> Defines emphasized text
<fieldset> Defines a border around elements in a form
<h1> This is heading 1
<h2> This is heading 2
<h3> This is heading 3
<h4> This is heading 4
<h5> This is heading 5
<h6> This is heading 6
<i> Defines italic text
<p> Defines a paragraph
<pre> Defines preformatted text
<q> Defines a short quotation
<samp> Defines sample computer code text
<small> Defines small text
<span> Defines a section in a document
<s> Defines strikethrough text
<strike> Defines strikethrough text
<strong> Defines strong text
<sub> Defines subscripted text
<sup> Defines superscripted text
<u> Defines underlined text
Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task.
However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.