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.
Some responses to Ned's responses, after which we shall all retire to the
bar for a round of drinks (on him!).
Note that I'm addressing only the easy questions, because it's Friday in Oz.
> Michael West wrote:
> > "Understanding the material" is _part_ of the technical communication
> > process, not a prerequisite to it.
>
> Where does it come in the "process"? First sounds right to me, but
> maybe it is the age-old question of egg or chicken first.
After you've determined the audience information need, you identify the
material that will satisfy that need. This is where "understanding the
material" comes in, because you have to understand what you are
communicating in order to know how best to communicate it. But you knew
that.
> > But even more "paramount" than that is
> > understanding the specific information need of the audience, and how it
can
> > best be met.
>
> The information has implicit structure and syntax. Where would you
> begin to understand the audience's needs if you didn't understand the
> information they're needing?
Where would you begin? Easy. By talking to them, or someone as close to them
as you can find. This is the step called "needs analysis".
The most useful way to approach it is via a task-based 'structure and
syntax'. What do they need to be able to do? What do they need to know in
order to do it? There's your subject matter.
>> Because nobody's paying you just to learn things that your
> > audience doesn't need to know.
>
> I'd be surprised to learn they're paying you or me to take the time to
> learn the concepts behind a product, needed or not.
Um. Could you run that past me again?
> For example, if the subject is network infrastructure development and my
> SME is the network architect, how many questioning looks should I expect
> to be allowed while he's checking me out with talk about octets and
> masks, vitualization, packets and protocols?
But you've left out the most important element in this interaction: the
audience. What are you trying to tell your audience how to do?
> > To whatever extent "our reputation is shot" (as Ned puts it), it isn't
> > because we aren't subject matter experts.
>
> So when I pick up a manual expecting to find information that
> comprehends what I need to know, and instead I find it has little blurbs
> of uninformative filler designed to make the manual look about the right
> size, it isn't because the writer isn't a subject matter expert. It is
> because ...
...because the writer didn't take the trouble to understand your information
need. And, sorry to be pedantic, but "information that comprehends" doesn't
quite gel as a concept. People comprehend. Information eases or interferes
with comprehension.
> > It's because we haven't learned
> > how, after gathering the right information from subject matter experts,
to
> > put it into a structure that our users find easy to access and easy to
> > understand. We haven't learned to speak the users' language and address
> > their specific information needs.
>
> Sorry, this may be your experience but it is not mine.
>
> For example, when I boot my PC and hit <Del> to set up BIOS parameter
> values, I need to know what those parameters are about. I look in the
> online BIOS help, but it is pathically uninformative. I look in the
> motherboard documentation, and it says exactly what the online help
> says. I trace the BIOS back to the manufacturer, who looks it up, points
> me to a web site where I can read the specification. I need a monster
> amount of knowledge to get what I need from the spec. It is very
technical.
>
> I don't think my problem, as user without much expertise, is supposed to
> be "learn all about BIOSes, although that is how I could approach it,
> given time. If the tech writers were rendered ineffective because they
> find a way to get the information to me, or to put the information in a
> form I could use, I think they'd at least have a way to provide what
> they COULD do, as a low- or no-cost electronic file on the manufacturer
> web site. Anything they can do to translate the manufacturer's spec
> into user documentation would be an improveent.
The problem as I see it is not that the tech writer (if there was one)
didn't "understand" the subject matter, but that it never occurred to that
vendor to provide step-by-step instructions to a user in "How To Set Up BIOS
Parameter Values". And if you or I had been the tech writer, Ned old bean,
we would have had the insight to know that it isn't enough to tell them what
switches to set; they need to know the results of the various settings in
order to choose intelligently between them. And if you or I had been the
tech writer, Neddy my man, we probably could have extracted all or most of
the information that the average user needs to set up the BIOS from the
"monster" spec and pared it down to a page and a half of essentials. And we
could have done that, Nedster, without being technical experts. Just
intelligent communicators!
> > Recently I was introduced to my firm's managing director by the CFO, who
> > said, "This is the guy I was telling you about. He's a translator from
techo
> > to Human."
>
> I'd just like to point out that this also makes my point, unless you can
> translate to Human without understanding the Tech.
Yes, in order to explain to a user how to (for example) process an invoice
using the new Godzilla Accounts Payable and Plumbing Repair System (GAPPRS),
I need to understand the procedure myself. But to do this successfully, it
is far more important for me to be able to speak "accounts payable clerk"
than it is to speak C++ (or name your poison.)
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
