One of the most common raps against XP isn't even true. People think we say that documentation is a bad idea. XP is focused on conversation for maximum effectiveness. Our recommendations on documentation follow from that simple fact.

We’ve discussed documentation here in other articles, including Natural XP: Documentation and Essential XP: Documentation. Here we’ll talk about our basic philosophy of documentation.

Warm versus Cool Communication

Extreme Programming relies on the Whole Team working together in a collocated situation. The key practices of On-Site Customer, Planning Game, and Pair Programming are examples: XP is about people in conversation.

This isn’t just a preference. Face to face conversation is a much more effective way of communicating. It’s this reliance on conversation that lets XP be as efficient and fast-moving as it is. It is a key contributor to the success of the method. Moving away from conversation slows down the entire process.

Now many other methodologies rely on cold documentation to transmit information about requirements, about design, and about the code. XP uses very warm methods of communicating these things: stories written on cards and communicated by conversation, design using CRC or sketches on a whiteboard, program knowledge transmitted by pair programming and collective ownership.

Therefore, we always resist when we’re asked questions like these:

  • Would it be better if we kept the stories in a database or Word documents or Excel? No, it wouldn't. Keeping the stories on inexpensive cards makes it easy to change them and replace them when someone gets a better idea.
  • Would it be better if we used project management software to manage the schedule? No, it wouldn't. Doing the scheduling with cards makes it no big deal to move things around and change the order of things.
  • Would it be better if we used a CASE tool to lay out the design? No, it wouldn't. The design is more readily expressed, changed, and understood when done less formally, with CRC or on the whiteboard or a bar napkin.
  • Would it be better if we used Javadoc to print out program documentation? No, it wouldn't. Focus on keeping the code clean and clear will pay off far more than commenting it and printing the comments. Working in pairs will communicate the details of the code far more effectively than Javadoc ever can.

Now don’t get me wrong (again). You may well need some nicely formatted UML for your project, or you may need to print out Javadoc when you distribute your code to other users, or you may need to document the requirements for management or as part of a contract. If and when you really need these things, then by all means you should do them. But inside your collocated Whole Team, you most probably will not need them, because the information you need will be communicated through the more effective medium of conversation.

It’s important, as early in an XP project as possible, that the Whole Team learn how effective these “low-tech, high-touch” mechanisms are. Therefore, we encourage newcomers to XP to stick to these basics until they’re intimately familiar with how well they work – and intimately familiar, as a result of using these mechanisms, with the other members of the team.

We trust – and you should trust – that the feedback mechanisms of XP will tell you in plenty of time if you have a real need to go to a cooler but more permanent way of communicating or recording project information.

Impact of the Wrong Amount of Documentation

You may still be concerned about having the wrong amount of documentation. More likely you’re concerned about having too little, but for many projects there is too much. Either way, it’s not that important, as long as the team is running on conversation, not paper. Keep that assumption in mind: you’re running the team on conversation. Now what if you don’t do the right amount of documentation?

Maintenance Documentation

Someday, if we ever release this program, it will go into maintenance. All the original programmers will be gone, and the maintenance programmers will need documentation.

Indeed they will. Suppose, because it’s the easier topic, that we have done too much documentation (admittedly unlikely). Well, the maintenance guys will quickly learn which parts of the documents are useful to them, and will ignore the rest. And while the cost of producing the useless documents will have slowed down the original development somewhat, the effect will be small and measurable – as long as the project itself runs on conversation. So no real harm will be done by doing more than we really need.

What if we don’t do enough maintenance documentation? Well, the world isn’t going to come to an end. First of all, the code is clear and clean. More imporant, maintenance programmers have been dealing with undocumented code for millions of years, and they’re very good at it. Initially, they’ll have trouble finding their way around in the program, but find their way they will. And – unless they are profoundly stupid – they’ll make the notes that are necessary to finding their way around.

External Documentation

Your project may – probably will – need to produce some forms of external documentation. You may need manuals. You may need status reports. You may need to publish requirements to outsiders, to publish interfaces to users, or to publish the design to some regulatory agency.

What does XP say about this kind of documentation? Is XP saying not to do these things?

It’s called Extreme Programming, not Stupid Programming. If your project really needs a document then of course you must produce it. The best way to do this is to have the Customer write stories requesting the documents, just like she would write stories requesting features, and schedule the documents into the iteration just like she schedules the other stories. The developers then sign up for the documentation stories and write the documents just as they sign up for programming stories and write the code. If your development team includes writers, so much the better. If not, no big deal. Programmers just sign up and write.

If you need a document, write it. How could you imagine that we’d recommend anything else?

Conclusions

Of all the things XP talks about, this one has generated the most heat and has the least impact. So long as you have the Whole Team collocated and using warm communication, the amount of documentation you produce has a low-order effect on successful shipping, and has a low-order effect on subsequent maintenance. If, however, you try to use cold documentation instead of warmer modes of communication, you can get into trouble. When documentation is used instead of personal presence to communicate requirements, design, or other ideas, that can really slow you down and introduce unnecessary misunderstandings. So don’t do that.

Otherwise, if you need it, write it. If you don’t need it, don’t write it. We trust you to figure out the difference.