TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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)
environment.
>
> 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
tasks-
> -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
unintentionally.
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. http://geocities.yahoo.com/ps/info1
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 http://ieeepcs.org/2001/
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 http://www.raycomm.com/techwhirl/ for more resources and info.
