The Art of Agile Development: Documentation

The second edition is now available! The Art of Agile Development has been completely revised and updated with all new material. Visit the Second Edition page for more information, or buy it on Amazon.

in 99 words

Projects use three main types of documents: work-in-progress; product; hand-off.

Work-in-progress documents communicate, and other forms of communication may replace them. High-bandwidth communication replaces some work-in-progress documents. Test-driven development creates executable low-level design specifications. Customer tests describe high-level behavior, and a ubiquitous language further clarifies intent.

Product documents have business value--schedule them with stories.

Handoff documents are best and most accurate at the end of the project. Set aside time after delivery to create them, and consider conducting an incremental handoff using pair programming and collective ownership.


The Documentation Myth

Full Text

The following text is excerpted from The Art of Agile Development by James Shore and Shane Warden, published by O'Reilly. Copyright © 2008 the authors. All rights reserved.


Whole Team

We communicate necessary information effectively.

The word documentation is full of meaning. It could mean written instructions for end-users, or detailed specifications, or an explanation of APIs and their use. Still, these are forms of communication—that's the commonality.

Communication happens all the time in a project. Some helps you get your work done; you ask a specific question, get a specific answer, and use that to solve a specific problem. This is the purpose of work-in-progress documentation, such as requirements documents and design documents.

Other communication provides business value, as with product documentation such as user manuals and API documentation. A third type—handoff documentation—supports the long-term viability of the project by ensuring that important information is communicated to future workers.

Work-In-Progress Documentation

Sit Together
Ubiquitous Language

XP has the whole team sit together to promote the first type of communication. Close contact with domain experts and the use of ubiquitous language create a powerful oral tradition that transmits information when necessary. There's no substitute for face-to-face communication. Even a phone call loses important nuances in conversation.

Test-Driven Development
Customer Tests
Ubiquitous Language

XP teams also use test-driven development to create a comprehensive test suite. When done well, this captures and communicates details about implementation decisions as unambiguous, executable design specifications that are readable, runnable, and modifiable by other developers. Similarly, the team uses customer testing to communicate information about hard-to-understand domain details. A ubiquitous language helps to further reveal the intent and purpose of the code.

The team does document some things, such as the vision statement and story cards, but these act more as reminders than as formal documentation. At any time, the team can and should jot down any notes that help them do their work, such as design sketches on a whiteboard, details on a story card, or hard-to-remember requirements in a wiki or spreadsheet.

In other words, XP teams don't need traditional written documentation to do their work. The XP practices support work-in-progress communication in other ways—ways that are actually more effective than written documentation.

Product Documentation

Some projects need to produce specific kinds of documentation to provide business value. Examples include user manuals, comprehensive API reference documentation, and reports. One team I worked with created code coverage metrics—not because they needed them, but because senior management wanted the report to see if XP would increase the amount of unit testing.

The Planning Game

Because this documentation carries measurable business value but isn't otherwise necessary for the team to do its work, schedule it in the same way as all customer-valued work: with a story. Create, estimate, and prioritize stories for product documentation just as you would any other story.

Handoff Documentation

If you're setting the code aside or preparing to hand the project off to another team (perhaps as part of final delivery), create a small set of documents recording big decisions and information. Your goal is to summarize the most important information you've learned while creating the software—the kind of information necessary to sustain and maintain the project.

Besides an overview of the project and how it evolved in design and features, your summary should include nonobvious information. Error conditions are important. What can go wrong, when might it occur, and what are the possible remedies? Are there any traps or sections of the code where the most straightforward approach was inappropriate? Do certain situations reoccur and need special treatment?

This is all information you've discovered through development as you've learned from writing the code. In clear written form, this information helps to mitigate the risk of handing the code to a fresh group.

Pair Programming
Collective Code Ownership

As an alternative to handoff documentation, you can gradually migrate ownership from one team to another. Exploit pair programming and collective code ownership to move new developers and other personnel onto the project and to move the previous set off in phases. Rather than a sharp break (or big thud) as one team's involvement ends and the other begins, the same osmotic communication that helps a team grow can help transition, repopulate, or shrink a team.


Isn't it a risk to reduce the amount of documentation?

It could be. In order to reduce documentation, you have to replace it with some other form of communication. That's what XP does.

Increasing the amount of written communication also increases your risk. What if that information goes out of date? How much time does someone need to spend updating that documentation, and could that person spend that time updating the tests or refactoring the code to communicate that information more clearly?

The real risk is in decreasing the amount and accuracy of appropriate communication for your project, not in favoring one medium of communication. Favoring written communication may decrease your agility, but favoring spoken communication may require more work to disseminate information to the people who need it.


When you communicate in the appropriate ways, you spread necessary information effectively. You reduce the amount of overhead in communication. You mitigate risk by presenting only necessary information.


Alistair Cockburn describes a variant of Extreme Programming called "Pretty Adventuresome Programming":1

1, accessed 24 May 2007

A PrettyAdventuresomeProgrammer says:

"Wow! That ExtremeProgramming stuff is neat! We almost do it, too! Let's see...

"Extreme Programming requires:

  • You do pair programming.

  • You deliver an increment every three2 weeks.

  • You have a user on the team full time.

  • You have regression unit tests that pass 100% of the time.

  • You have automated acceptance tests which define the behavior of the system.

"As a reward for doing those,

  • You don't put comments in the code.

  • You don't write any requirements or design documentation.

"Now on this project, we're pretty close...

  • well, actually a couple of our guys sit in the basement, a couple on the 5th floor, and a couple 2 hours drive from here, so we don't do pair programming,

  • and actually, we deliver our increments every 4-6 months,

  • we don't have users anywhere in sight,

  • and we don't have any unit tests,

"but at least we don't have any design documentation3, and we don't comment our code much! So in a sense, you're right, we're almost doing ExtremeProgramming!"

Those people aren't doing XP, they are doing PAP [Pretty Adventuresome Programming]. PAP is using XP (in name) to legitimize not doing the things one doesn't want to do, without doing the XP practices that protects one from not doing the other things. E.g., changing the code all the time, but not writing unit tests; not writing documentation, but not writing clear code either. Not...(almost anything)... but not sitting close together. etc4.

2Most teams now use one or two-week iterations. I recommend one-week iterations for new teams; see Iteration Planning in Chapter 8.

3Emphasis in original.

4Alistair later added, "I am interested in having available a sarcasm-filled derisively delivered phrase to hit people with who use XP as an excuse for sloppy, slap-dash development. I, of all people, think it actually is possible to turn dials to different numbers [Alistair means that you don't have to go as far as XP does to be successful], but I have no patience with people who slap the XP logo on frankly sloppy development."

Sit Together

In other words, continue to create documentation until you have practices in place to take its place. You have to be rigorous in your practice of XP in order to stop writing work-in-progress documentation. Particularly important is a whole team (with all of the team roles filled—see The XP Team in Chapter 3) that sits together.

Some organizations value written documentation so highly that you can't eliminate work-in-progress documents. In my experience, these organizations usually aren't interested in trying XP. If yours is like this, but wants to do XP anyway, talk with management about why those documents are important and whether XP can replace them. Perhaps handoff documents are an acceptable compromise. If not, don't eliminate work-in-progress documents. Either schedule the documents with stories or include the cost of creating and updating documents in your estimates.


If you think of documents as communication mechanisms rather than printed paper, you'll see that there are a wide variety of alternatives for documentation. Different media have different strengths. Face-to-face conversations are very high bandwidth but can't be referenced later, whereas written documents are very low bandwidth (and easily misunderstood) but can be referred to again and again.

Alistair Cockburn suggests an intruiging alternative to written documents for handoff documentation: rather than creating a design overview, use a video camera to record a whiteboard conversation between an eloquent team member and a programmer who doesn't understand the system. Accompany the video with a table of contents that provides timestamps for each portion of the conversation.

If you liked this entry, check out my best writing and presentations, and consider subscribing to updates by email or RSS.