ONJava.com -- The Independent Source for Enterprise Java
oreilly.comSafari Books Online.Conferences.

advertisement

AddThis Social Bookmark Button
Article:
  An Introduction to Extreme Programming
Subject:   What about documentation?
Date:   2003-04-22 06:13:04
From:   anonymous2
Response to: What about documentation?

The approach to documentation is both pragmatic and scary.


- Only do the documentation that adds value:
- Since documentation external to code tends to drift relative to code, document as much as possible within the code.


The first point is scary since it is hard to asses documentation value while in the midst of the development frenzy that XP supports. The second is achievable for internals documentation using tools like .e.g. doxygen.
The piece of the pragmatic approach I like is the recognition that diagramming and other modelling techniques are just that: modelling techniques: Modelling should be done to enhance or communicate understanding.
Modelling to the 'bitter end' serves no function except to support 'round-trip' model <--> code, and I have never seen systems that support this that can take a cycle through that and leave you with understandable diagrams.
So I think it's a good thing to question the usefulness of the documentation we have been trained to produce compared with the value added to the system in terms of understandability and maintainability, but a danger that this value will be mis-evaluated in the rush to meet that release goal.