RE: Just do it

Subject: RE: Just do it
From: "Giordano, Connie" <Connie -dot- Giordano -at- FMR -dot- COM>
To: "'kfshea -at- sci-techconsult -dot- com'" <kfshea -at- sci-techconsult -dot- com>, TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 6 Sep 2000 12:15:31 -0400

Once again, several have missed Andrew's point. Had your newbie TW asked
questions and experimented with Robohelp, in addition to watching you work,
and then asked some more questions and experimented some more, he'd have had
more of a clue and his document would have been a mite more useful. Had he
handed any of us a well-masticated, overplanned survey on whether we thought
the documentation for Robohelp was useful or not, and never tried anything,
he'd never have a clue about how Robohelp really works.

Some of the posters hit it on the head, if you have no other method to get
feedback, try a survey, but don't be surprised if you get no response, or
very little useful feedback. In all my experience, everytime we sent out a
survey or a feedback card, we never got a single response. When we sat down
and worked with tech support, we got all sorts of interesting grist for the
doco mill. Even more useful was on-site observation, not of how they use
the documentation, but of how they use the product. That, combined with
lots of trial and error on our own, and questioning of the various SMEs is
what makes useful doc. A pretty self-addressed stamped envelope with scaled
questions just isn't a substitute for research and experimentation. The
documentation may never be able to address every nuance, but it's more
likely to hit all the major needs in a useful way.


Connie Giordano
Senior Technical Writer
Advisor Technology Services
e-mail: Connie -dot- Giordano -at- fmr -dot- com

"Tell me and I'll forget. Show me, and I may not remember. Involve me,
and I'll understand." - Native American Proverb

-----Original Message-----
From: kfshea -at- sci-techconsult -dot- com [mailto:kfshea -at- sci-techconsult -dot- com]
Sent: Tuesday, September 05, 2000 8:00 PM
Subject: RE: Just do it

This idea that writing must be prefaced by experience sounds good in
theory, but can be a bit unrealisitic in practice. Sure, you can learn how
to 'go through the motions', but unless you're documenting something as
stepwise as the McDonald's procedure for deep-frying hash browns, the
notion that by doing a task or set of tasks a handful of times allows you
to 'get into your customer/user's head' and 'address all the nuances of
doing a job' sounds like a misguided attitude.

I agree that having a sense where, when, why, etc., a task is performed is
extremely important. But dismissing questions as a valuable asset and
pinning everything on being able to learn every task that you have to
document seems a bit over-confident. Maybe if all of your documentation is
within one subset of a field this experience comes with time. But if you
move across fields and industries, it's a ridiculous assumption that you
can come in and learn a set of tasks it has taken another intelligent,
coordinated, and competent individual years to master. From my experiences
as a worker whose tasks were being documented by just such a putz, I can
tell you that coming into a shop with attitudes like this is the quickest
way to get no input at all from the expert users - and that makes producing
quality documentation impossible.

Imagine a technical writer who has never turned on a computer coming into
your place of work, seating himself in an adjacent (masticating) cubicle,
there to document the set of procedures that must be followed to run
(RoboHelp, Word, Frame, PhotoShop - insert your favorite (software) tool).
He doesn't want to appear to be a work-shirking, hang around your office
type of writer, so he doesn't ask you a thing about how anything works. A
day, or a week, later (assuming he gets the computer turned on) our writer
emerges from his lonely cubicle, frowsty from the effort, but ever so
complacent in the knowledge that he, too, is an expert RoboHelp'er. He
proudly calls you over to share in his glory - he is a RoboHelp-using
muther. The catch (there always is one) is that the result of his efforts
is a piddling figment of what you produce on a daily basis. There are no
nuances, no clever uses of the software's strengths, no inspired
workarounds of the software's inevitable flaws and shortcomings. And the
most galling thing of all is that this sucker now thinks he "knows" your

Take these attitudes out into the (real) non-computer world and the concept
that a writer can learn how to: fix and re-install a transmission, repair a
BOP stack on an oil rig, run a TIG root bead, etc... by spending a finite
amount of time rolling up his sleeves and setting to it demeans and
diminishes the long hours and years of experience garnered by the people
who really know the job.

If all you document are tasks that require very little in the way of
expertise or experience, I'd say that Andrew's single-minded approach will
suffice. But, I feel, at some point, you have to get feedback, whether that
is a survey, or walking around a break room, buying coffee for the hands
that do the work in return for picking their brains, it doesn't really

Another aspect to this is: What employer is going to pay me, a freelancer,
to come into her shop and spend time learning how to do a task until I'm
"in the user's head" and have learned *all* of the nuances? Unless she
wants to hire me to do the task fulltime after the document is complete, I
don't think anyone bargains on paying me my rate to become another skilled


Previous by Author: RE: The case for use cases
Next by Author: RE: .chm to hlp?
Previous by Thread: RE: Just do it
Next by Thread: RE: Just do it

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

Sponsored Ads

Sponsored Ads