Re: Agile Blogs?

Subject: Re: Agile Blogs?
From: "Michael West" <mbwest -at- bigpond -dot- com>
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 3 Mar 2009 21:36:26 +1100

Julie wrote:

> The developers are still figuring out how Agile is going to work here,
> so they're not a whole lot of help in defining my role on the team.
> They seem to think it will just work itself out somehow. And it
> probably will, I'm just impatient to know how it will turn out. The
> upside of that is that *I* get to establish how the tech writer fits
> into our Agile processes. At the moment I'm one writer only dealing
> with a single scrum team. I'm really curious to hear from other
> writers how they fit into their teams, or don't.
> Julie


I've been working as a tech writer with an Agile team for almost two years
and it has been, overall, a very satisfying experience. In fact, one of the
best experiences I've had in 25 years of technical writing. The team
respects what I do and I respect what they do. But WAAAY more importantly,
the customers respect what I do and see it as an indispensible part of the
deliverable -- not an add-on or a nice-to-have. They won't accept software
that is not accompanied by appropriate user training and/or assistance in
some form. Bless their twisted little hearts. When they define requirements,
my stuff is ALWAYS part of what they define. (Okay, I do coach them a bit
about what kind of material might be most useful in a given situation.)

A lot depends on whether you are developing enterprise software for in-house
customers whom you can interact with daily, as I do, or developing for the
commercial marketplace for customers whom you will never meet. I've done
both, and the first is so much more satisfying that I don't think I could
ever be happy going back to writing for an invisible, phantom audience.

If you are writing for in-house customers, then here is my advice. Treat
user assistance in the same way the team treats "user stories." Make the
user assistance requirements into user stories: "As a financial accountant I
need a set of instructions telling me <how to process a xxx transaction> or
<what to do when I get this error message>".

Don't leave things vague and unspecified, as in "As a user I want some
documentation." What in hell does that mean? Could mean just about anything.

Me, I don't read or write blogs because I find them the most tedious,
pompous, self-congratulatory things on the planet. But I'd be happy to share
ideas and advice on this list or privately.

One way you can benefit the team from day one is to help them write user
stories that are well-constructed. You can check out Mike Cohn and Scott
Ambler for good guidelines. This will not only help them understand what
they're supposed to be doing; it will also help you because every
well-constructed user story is also a user-assistance requirement crying to
get out. If the user story is "I need to be able to process xxx
transactions" -- that's a developer's task (write the code) AS WELL AS a
tech writers task (explain how to do it). See? "Being able to do it" doesn't
just mean having a tool that can do it. It also means knowing HOW TO USE THE
TOOL. The task isn't complete until you've both -- developer and tech writer
(or trainer or both) -- done your part.

Good luck.
Mike west


ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals.

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Please move off-topic discussions to the Chat list, at:


Previous by Author: RE: HyperSnap DX question
Next by Author: Re: Someone to do the "donkey work"? (take II)
Previous by Thread: Re: Agile Blogs?
Next by Thread: Re: Agile Blogs?

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

Sponsored Ads