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.
Subject:RE: Just do it From:kfshea -at- sci-techconsult -dot- com To:techwr-l Date:Wed, 6 Sep 2000 9:0:43
Andrew Plato wrote:
Second, no survey can possible address all the nuances of doing a job.
There are countless little issues and gotchas that never get into a survey
or get considered.
....At some point you have to learn about the topic and what users do. If
you're really serious about "getting into your customer/user's head" then
do their job for a while.
When I wanted to know how to install and setup stored procedures in a
client's Oracle database - I learned how to do it. It was a breeze
documenting it once I knew how to do it. I knew *exactly* what the users
would need to know because I was a user for a while. I also understood all
the little idosyncracies of doing it, particularly what to warn the user
and how to communicate complex steps.
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