Re. Getting writers up to speed on the product?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Michelle Parcell <<...has had an established documentation department for
several years (at least 10), [but] it has not     been standard practice for
the writers to use the software about which we are writing. We rely on specs
and experts' review for accuracy.>>

Wow! You actually have specs good enough to let you write docs? That's
pretty rare. But even so, I can't imagine documenting something I can't play
with. (There's an analogy about describing sex to virgins, but since this is
a family forum, I won't mention it. <g>) This inevitably means that you're
missing out on one of the most important aspects of documentation:
experiencing firsthand what your audience experiences. That's the only real
way to pick up interface flaws and to get a visceral grasp of how users
approach the task of producing something with the software. Nothing's more
effective at building empathy for the audience than putting you in their
shoes, however briefly.

<<Does your company have an established training regimen or product
orientation for new writers?>>

We're not big enough and we don't produce enough software (yet!) to need
anything formal. Instead, when the product is stable enough to start
documenting, I get an overview of what it does from the developers, install
a copy, play with it for a while, then go back to the developers with
questions about anything I don't understand. Once I've got a good grasp of
where the bodies are buried, I start documenting the product, accompanied by
periodic visits to the developers when I hit a brick wall or when somebody
moves the bodies. <g>

<<what do you think is the best method for educating new writers on
products?>>

Treat them as if they're a new user who just purchased the product: give
them the existing docs, an overview of what the product's supposed to do,
and turn them loose for a day (warning them that they're not expected to
produce any results beyond figuring out how things work... and more
importantly, how they don't work). They'll very quickly pick up on things
you've missed (usability issues) in both the software and the documentation;
these are all things you won't see because you've been staring at them so
long that they're part of the natural landscape now. Then sit down with them
and start talking about where you're going with the product. (Have a look at
my article in the Sept./Oct. 99 issue of _Intercom_, "Nurturing a new
writer" for more detailed suggestions.)

--Geoff Hart, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca 
"The paperless office will arrive when the paperless toilet
arrives."--Matthew Stevens