Article:		An Introduction to Extreme Programming
Subject:		What about documentation?
Date:		2003-01-28 12:33:30
From:		anonymous2
Does anyone have experience producing effective documentation in this type of development environment? It sounds like it would be hard on the writers. Or is there a way to manage it? Thanks!

Showing messages 1 through 3 of 3.

• How I can Make XP documentation?
  2004-12-01 03:47:40  qasem1 [View]
  
  
  Please, if you can tell me of how I can buid an XP documentation. and it can be done by making documentation for each phase (plane, design, code and test) or all in one documentation?
  
  Thank you very much

• What about documentation?
  2003-10-21 02:25:02  anonymous2 [View]
  
  
  Documentation is *always* hard on the writer, just as programming is. But it can be fun, just as programming can.
  
  I'm not doing XP but I've done something that looked suspicously like quick-and-dirty that had to be tested by someone a long way away who didn't fully understand what I had produced. During development I circulated specifications in the classical manner, and had them not read and not signed off also in the classical manner.
  
  For my tester, who was in much the same position of ignorance as a real user, I had to write a whole load more text to explain how to use the system so he could test it. Hurrah! A user manual, though not presented as such, and not nearly complete. Still, it truly reflected the softrware because it was written alongside the development, slightly lagging.
  
  I'd suggest doing two things. First ask: who's going to read this and what do they want out of it? (Be honest, which bits of the documentation for "closed" projects do *you* read?) Second, treat those documents that you still want to produce as part of the development. Deliver them along with the code, get them accepted by the customer (or not).
  
  Thirdly (out of two?) get the documentation tested. Find some poor fellow who doesn't know the system and get them to try using it taking your document as guidance. Watch them try to get help on a topic where they don't know the keyword. Hear them snore over the contents list. Demand honest feedback. Good luck!

• What about documentation?
  2003-04-22 06:13:04  anonymous2 [View]
  
  
  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.