Traditional projects frequently devote a significant portion of their time on writing documents for all kinds of different purposes. While some of the documents seem to make sense, there are also documents, which are created for their own sake only.
Opposed to that XP has no documentation by default. Instead, documentation is created only, if there is no way to avoid it. There are other artifacts, such as index cards, which you might call "documentation". However, this is not what I refer to here.
This article describes the role of documentation in XP, discussing benefits and liabilities of documentation in general, and giving advice about what to do with documentation.
Many documents are created in some software projects. Just to name a few, here is a short list:
You probably can easily add items to this list. Just have look at some of the projects you have worked for, or which you have heard of.
Lets look at the reasons, why these documents are created. Depending on the type of the document, the reasons vary. In some cases it its the customer, who requires you to create the document. In other cases it might be mandatory for gaining approval by a government agency; then, you have not alternative.
But there are also documents, which are simply written, because the "software development process" tells you to do so. There might also be historic reasons ("We have always written a <fill in your favorite>!"), or there might be ignorance: people simply have not thought about alternative ways.
Documentation serves the purpose of communication. Their first advantage is that you can easily address a large audience, for instance by publishing the documentation on a web server.
Another advantage is the time you have to prepare and rethink what you document. Compared to that in direct interactive communication you don't have the time. How often have you experienced that you discover your best arguments or counter-speeches after the discussion is over.
Another benefit is, that you cannot only use plain text, but also pictures, drawings, tables, and that you can mix them at your discretion. Also, the amount of information in a document of 50 or 100 pages can potentially be much more than what you can cover in an entire day full of meetings.
Communication is one of the four values, upon which XP is based. Therefore, documentation is good. Is it? Not in all cases.
First, you should ask, whether written documentation is the best way to cover your communication needs? As alternatives, you may select one from the following list:
In all cases, you increase the likelihood for more interaction. A written document is mostly uni-directional. Seldom, the author is eager to change a document frequently, even if much feedback is available. Still, it requires much work on both the author's part and the reader's part.
Even if you would be willing in general to create the documentation, you still have to think of resource limitations. Where do you want to put your resources to work? Does it create the most value for the customer, if programmers write documentation? Or does it create more value, if programmers work on implementing features?
When programming we have to write code. We need code for acceptance tests, for unit tests, for the system itself. So why not write code instead of documentation? So why not write code in such a way that it can replace documentation in almost all places?
There are XP programmers who claim that acceptance tests, if written by the customer, represent the requirements. And I agree with Scott Ambler, who states: "You know what? They are right!"1
In our project, we have observed that we write almost no comments in our code. Still, it is understandable and maintainable. So towards this respect the source code looks different than in previous projects, in which a traditional approach was chosen.
If your customer requires you to write some sort of documentation, then you have a perfect means of making explicit the necessary effort. Just create a user story and make an estimate for it. Then the customer can see how many other features will not be implemented, because of writing the documentation. Then, the customer can make a sound decision.
Documentation can be good or it can be bad. It is not possible to make a final statement. It depends. From an XP perspective, always think about how far you can get, if you simply don't create a specific document.
Also, in some cases people think that documentation comes for free automatically with the system; by employing user stories XP provides a mean for making the required effort and the tradeoff between additional documents versus additional functionality explicit.
Finally, here is a story which I was told by a senior executive:
When he was a young engineer he was asked to write a document. The sense for doing so was not clear to him. So he told his manager, that there was no sense in writing the document, so he would not write it. His manager insisted on writing the document. The young engineer decided to just write the first ten pages or so and he skipped the major portion. Then at the end of the document, he put in a phrase similar to the following: "If you reach this point in the document, contact me, and I will pay you 100 US-$." The young engineer submitted the paper knowing that 90% was missing. Yet, he never had to pay! Some time later he became the manager of his former manager.
1) Scott W. Ambler: "Agile Modeling: Effective Practices for eXtreme Programming and the Unified Process", page 217. Wiley, New York, 2002.
© Copyright 2001-2002 by Manfred Lange, All rights reserved. Terms of use.
Last change: