RE: Managing documentation in a rapid/agile/extreme programming e nvironment

[Jason Willebeek-LeMair <jlemair -at- cisco -dot- com>]

-----Original Message-----
From: Richard G. Combs [mailto:richard -dot- combs -at- voyanttech -dot- com] 

There's a short, breezy article at XProgramming.com that I've had on my cube
wall for some time now, with lots of yellow highlighting:

"Manuals in Extreme Programming," Ron Jeffries
http://www.xprogramming.com/xpmag/manualsInXp.htm

Here are a couple of quotes:

<snip/>

"Document as you go... Documenting a feature shouldn't be any more difficult
than implementing it. If your programmers can invent the bloody thing from
scratch in one iteration, your writers ought to be able to write it up in
the same time and stay only one iteration behind."

<snip/>

------Jason's Reply------

I liked the article.  The only thing that really struck me as being mildly
wrong-headed and overly-simplistic was the above excerpt.  It seems to
assume a 1-to-1 ratio of writers to programmers.  

What happens when you have several programmers, or in my case, several TEAMS
of programmers contributing to each iteration?  Sure, one writer should be
able to document the changes of one programmer (excluding, of course, global
changes where a coder can change controls across the app and invalidate
every screenshot in the application).  Maybe even two or three.  However,
lag gets introduced when you get 4 or 5 new features, 6 or 7 changes to
existing features, and a global control change in one iteration.

Of course, you can mitigate the lag.  Work with dev on the feature branch
rather than the mainline, work from specs, get a framework in the first
iteration and beef it up the next, partner with the testing group to use
their automated testing framework to keep screen shot up to date, and so on.

However, a blanket statement that the writer should be able to keep up
really ignores the reality of most development environments, where the
number of developers contributing features to an iteration is far greater
than the number of writers supporting those features.

Jason