Re: User Documentation in XP environment (Possible Process)

Subject: Re: User Documentation in XP environment (Possible Process)
From: Andrew Plato <intrepid_es -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 3 Oct 2001 14:11:23 -0700 (PDT)

"Laura spencer" wrote...

> For those colleagues working in an Extreme Programming environment, I
would like feedback on the following:
> With a colleague, I have come up with a possible process for writing
online help and user documentation in an XP (Extreme Programming)
> We discussed having each story contain a simple task which basically
> requires that decision be made about whether that story should be
> documented (yes or no), and that each iteration contain a story to write

> the user documentation. The user documentation should contain two
> -one for the writer and one for the reviewer. The task for the writer
> is simply to document the stories that were designated as needing
> documentation from the prior iteration. The task for the reviewer is to

> review the documentation.

I've never documented anything in a XP environment...most places just
coded their apps and didn't much consume themselves with giving their
methods some name. But, based on what I have read about XP - its ideas are
rather common in many development environments - either intentionally or

However, as I understand XP, the whole idea is that you elminate the
tremendous amount of planning and architecting that is traditionally done
in complex development projects. You establish basic goals, jam out code
and see if it works. If it doesn't you scrap it an build something new.

I have always found this the most effective way to document complex things
as well. Learn the product, jam out text and/or graphics, run them by
engineers to see if they work. This often requires jumping around a lot
and throwing away material that has become dated.

It seems to me that you are trying to derive a hard-and-fast process from
an XP environment, when one of the whole points of XP is to avoid
hard-and-fast processes.

Why don't you try just jamming out docs and having them reviewed when you
hit logical break points. Don't try to organize everything into neat
little cubes from day one. Just write the docs and move along. One of the
other concepts in XP is to leave optimization to the end. Don't make it
perfect, just get the material written.

Remember, there is always another revision down the road.

Andrew Plato

Do You Yahoo!?
NEW from Yahoo! GeoCities - quick and easy web site hosting, just $8.95/month.


Planning to attend IPCC 01, October 24-27 in Santa Fe? Sign up by
October 3 and get a substantial discount! Program information,
online registration, and more on

Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: RE: warranty or liability and thanks
Next by Author: HUMOR: Blame Guide
Previous by Thread: RE: User Documentation in XP environment (Possible Process)
Next by Thread: Returning to normal? - TECHWR-L

What this post helpful? Share it with friends and colleagues:

Sponsored Ads