Elizabeth Keogh wrote an article about documentation on agile projects. I had a few too many thoughts to compress into one comment, so here they are.
Perhaps a better idea than writing all the documentation at the end is to write documentation as you go, but generate it from the code as much as possible.
Obviously, just writing javadoc for every method would not be what you want. In some ways, you'd have too much information (like a redundant summary of each method), and in other ways you'd have too little -- there'd be no high-level overviews.
Instead, you need a few rules to reduce redundancy as much as possible:
Don't write documentation that explains what the code does, at least at a low level.
As Elizabeth has more recently said, well-written code is to some degree self-documenting. Unit-tested code is even more so. This might need to be explained to the customer, when she asks why you haven't documented the system at a low level.
For each class or sub-system, record high-level information that is going to be useful. Maybe you could get your developers to write CRC notes in the header, or a separate file.
Develop a method for including diagrams, external document snippets, etc. Diagramming UML in XML is now available, if not completely standardised. If you need a really glossy result, you could include/generate WordML or LaTeX.
When using names of units of code in your documentation, use some kind of reference. These need to be able to change automatically when you rename classes, etc.
Would an approach based on rules like this make documentation maintainable and less redundant?
I definitely agree with Alan, documentation should be prioritised and approved by the customer, with an understanding of the tradeoffs (less code written, more time to maintain it, good coders aren't good writers).
However, the customer is also looking for technical advice from the dev team about the best way to approach things. I'm not sure that recommending waiting until the end is the most effective way, especially if one of your customer's goals is maintainability after you're gone.
I suppose that points to a problem with XP, and probably development in general. When the customer's prioritisation conflicts with their long-term goals, should an XP team point this out, or do they take the customer's prioritisation as gospel? For example, the customer might under-prioritise documentation because it doesn't help them win the short-term sales, and only once the consultants are gone do they realise they need documentation to get new people in to work on new features.
This has turned into too much of a rant, so I'll post it on my own blog.
