Managing documentation in a rapid/agile/extreme programming environment: followup

[Robert_Johnson -at- percussion -dot- com]

Many thanks to those who responded to my request on this subject 
yesterday.  To summarize:

Bonnie Granat recommended an article from STC:  Carl Nuckols and Jeff 
Canna, "Extreme Documentation" (_Intercom_, Vol. 50, No. 2, February, 
2003, pp. 6-9).  This article is a good introduction to the concept of 
extreme programming and some ways documentation can fit into such an 
environment.  Not alot about managing documentation in that environment, 
though.

Several people pointed to "Manuals in Extreme Programming," Ron Jeffries (
http://www.xprogramming.com/xpmag/manualsInXp.htm).  It was an interesting 
article, and reminded me of a frequent poster to the list.  And while 
Jeffries point about integrating documentation into the iteration cycle is 
well taken, I think he's a bit too blithe dismissing documentation as 
"just reporting, after all".  I think there's a bit more to it than simple 
reporting.  I also dispute his point that "Your customer hates big 
manuals."  Initially, against my recommendation, we only provided online 
Help for our enterprise CMS product.  Some customers howled in protest 
against the absence of manuals, one even demanding a stack of manuals the 
size of the NYC phone book for such a product.

Eric Ray recommended the use of Wiki's as an authoring and commenting 
mechanism.  It's an interesting idea I'll investigate.

John Cornellier questioned the "the difference between 'creating 
documentation' and 'managing user documentation'".  As I indicated, my 
supervisor wants to know how we're going to fit documentation into the 
agile process the department is adopting.  Saying "we'll just do it" is 
not going to suffice.  Moreover, just as people want to know what their 
going to be getting for documentation just as they want to know what 
they're going to be getting from the product.  This may be a place where 
Jenny Berger's story cards come into play, or some perhaps similar 
lightweight mechanism to keep people informed about what we will be 
delivering.

GooberWriter questioned my assertion that Hackos's approach does not adapt 
to an agile/rapid environment effectively.  I may have overstated that 
assertion.  I'm considering an approach similar to the lightweight 
information plan Peter Hartman recommends in _Starting a Documentation 
Group_, but maintaining the plan as a living document through the 
development cycle.

I have some ideas I'm going to propose now.  I'll let the list know how it 
proceeds.  Perhaps there's an STC presentation or Intercom article in 
this.

Thanks again to all that responded.

Bob Johnson
Documentation Specialist
Percussion Software
Stoneham, MA