The Art of Agile Development

Documentation

Note

Whole Team

We communicate necessary information effectively.

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

Communication happens all the time in a project. Sometimes it 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

In XP, the whole team sits 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.

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