In-Depth

Documentation that’s barely sufficient makes the grade

• By Stephen Swoyer
• March 1, 2005

Agile methods such as extreme programming place a much greater emphasis on user involvement, pair programming, and refactoring than on planning and documentation. In XP, for example, documentation typically consists of ideas (user stories) scribbled on index cards. These user stories are based on feedback from "customers," in fact, they're more or less written by line-of-business representatives, and are designed to replace the copious requirements lists most programmers are familiar with.

This alone is enough to give project management squares (and compliance officers) the heebie-jeebies. For many agile advocates, that's the point.

"There's been too big a reliance on documentation for conveying critical information about a project, and we have basically used documentation to substitute for interaction," says Jim Highsmith, an agile pioneer who helped develop the Scrum project management methodology. Highsmith currently serves as director of The Cutter Consortium's Agile Project Management Advisory Service, where he frequently encounters this problem. "What I tell people is that when documentation is a substitute for interaction, that's a problem. But when documentation is used to supplement the interaction that's already there--that's what you want to use it for."

Of course, a lot of the concern about agile's documentation-lite approach is overblown: XP programmers and coders who work with other agile methods practice what might be called barely sufficient documentation, which they say typically involves documenting just enough to satisfy the specific requirements of one's organization. The important thing, they say, is to not let the process of documentation slow down or otherwise impair the collaborative brainstorming, coding, and testing activities that are seen as key to agile's success.

"If you get the customers and the business analysts talking directly to the programmers, and they document a few things on cards, and somebody goes back and documents these as something else for audit requirements, for compliance requirements, then that's fine," Highsmith explains. "You do the amount of documentation that you need to do for these things. In an agile environment you end up doing barely sufficient documentation."

Back to feature: Agile Breaks on Through to the Other Side