Re: Technical Writing in an Extreme Programming Environment

["Lorraine Kiewiet" <lkiewiet -at- earthlink -dot- net>]

Paul,
I was also the "lone writer" in an XP environment (Java, XML, and a
Window-based GUI tool).

The "user stories" where helpful to me in building an outline of the work
to come. I was using WebHelp (from eHelp) to document the GUI tool and
placed the user stories in the Comments fields, or sometimes right in the
text. This reminded the engineers of why I had a place-holder somewhere, so
we could flush out the details of the user story.

My manager wrote an article about managing an XP team, and mentioned the
fact that the user stories helped the documentation effort (me) and the
team as a whole.  Also, I would sometimes be the scribe for XP user story
development meetings. Since tech writers sometimes whine that they are
excluded from critical development meetings, the XP method almost requires
your presence. You can also use your prototype online documentation,
written from XP user stories, to ship with an Alpha version of the software.

The book about XP that we used ("Extreme Programming Explained; Embrace
Change" by Kent Beck) does not mention the benefit to the documentation
effort. In fact, the sole reference to documentation is that XP helps you
get rid of the need for a lot of it. (but not for end-users, of course) 
The original idea is that the the user stories *are* the documentation. 

--Lorraine

Here's one paragraph from the article:

Our technical writer discovered another side effect.  She noticed that our 
user stories became the table of contents and summary of features necessary
for the software documentation.  Documentation outlines are developed
immediately and filled in as the   software matures.  The documentation
then serves as an early glimpse and can be part of usability testing . 
This also works for requirements since user stories are written
descriptively, from the point of view of the user experience.

> ----------------------------------------------------------------------
> 
> Subject: Re: Technical Writing in an Extreme Programming Environment
> From: Paul Gerle <PaulG -at- mdli -dot- com>
> Date: Tue, 11 Sep 2001 07:53:12 -0500
> X-Message-Number: 6
> 
> 
> Laura Spencer wrote:
> 
> <  I would like to learn more a) about how many other writers are working
in
> <  an Extreme Programming environment b) how (or if) Extreme Programming
has
> <  changed the way you work.
> 
> I, too, am working on my first project utilizing extreme programming, and
I
> find, with few exceptions, that very little has changed the way I document
> the development process from the traditional "waterfall" model of
> development.
> 
> Let me say, though, that I am the sole writer on a project consisting of
> four developers, a lead architect, just one QA resource, and a handful of
> SMEs defining the requirements.  We're developing in Java for an ASP-model
> program.  Very complex.
> 
> I find the biggest difference in an XP environment is simply the
uncertainty
> about what's coming next.  I don't know today exactly what I'll be working
> on next week.  It's human nature, I believe, that some folks always like
to
> know what's around the corner, while others are OK "winging it".  It's
each
> individual's call.
> 
> Also, my particular organization (I'm consulting through an agency for
this
> client) has one problem with scheduling.  They want the advantages of XP
> (shorter development time, more flexibility to requirement/scope changes)
> AND the "security" of accurate estimates of costs on the project.
> 
> That is, they're demanding a schedule and cost estimates for modules of
the
> software that aren't even defined yet.  How do we know how long a module
> will take to build when the requirements analysis, design, and testing
> requirements are not scheduled to begin for six months?
> 
> So, if you're comfortable with having only a week's worth of work spelled
> out at a time, and you're confident you can manage the stakeholders'
> expectations, working in an XP environment doesn't seem to me to be
> fundamentally different from a traditional one.
> 
> Paul Gerle
> "I can write better than anybody who can write faster, and I can write
> faster than anybody who can write better." 
> 	- A. J. Liebling (1904-1963) 
> 
> 



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A landmark hotel, one of America's most beautiful cities, and 
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe.  http://ieeepcs.org/2001/

  +++  Miramo -- Database/XML publishing automation.  See us at  +++
  +++  Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion  +++
  +++ More info: http://www.axialinfo.com  http://www.miramo.com +++

---
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.