Can Documentation Be Agile?

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 application—if you choose to make it so. Here are 12 steps you can take to ensure your documentation is agile:

1. 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.
2. Keep it just simple enough, but not too simple. The best documentation is the simplest that gets the job done. When creating documentation, follow AM's principle, Use the Simplest Tools ( http://www.agilemodeling.com/principles.htm ), and its practices, Create Simple Content and Depict Models Simply ( http://www.agilemodeling.com/practices.htm ).
3. 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.
4. Document with a purpose. Create a document only if it fulfills a clear, important and immediate goal of your overall project.
5. 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.
6. 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.
7. 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.
8. Display models publicly. When you publicly display models—on a whiteboard, corkboard or internal Web site—you'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.
9. Document current models first. If you keep a model up-to-date, it's probably valuable—and therefore worthy of documentation.
10. 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.
11. 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 for overlap.
12. Get help from an experienced writer. Technical writers know how to organize and present information effectively. Also, write documentation with a partner—just 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 rewards—which do you prefer?

Refactoring Persistence
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.htm—hope you decide to get involved.

Suggested Links:

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.

Agile Modeling Feedback Page
http://www.agilemodeling.com/feedback.htm
This page offers instructions for joining the mailing list, as well as archived messages.

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.

Communication
http://www.agilemodeling.com/essays/communication.htm
This essay discusses the various means of communication available to software developers, comparing and contrasting their effectiveness.

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 databases difficult.

Refactoring Home Page
http://www.refactoring.com

Santa Fe Institute
http://www.santafe.edu/
This site hosts a large collection of papers, several of which address the concept of emergence and evolutionary development.

Related Reading

More Insights

INFO-LINK

Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

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.

	To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.