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


AddThis Social Bookmark Button
  An Introduction to Extreme Programming
Subject:   What about documentation?
Date:   2003-10-21 02:25:02
From:   anonymous2
Response to: What about documentation?

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!