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: Researching your Subject From:Ben Kovitz <apteryx -at- CHISP -dot- NET> Date:Mon, 21 Dec 1998 12:59:17 -0700
Doug Nickerson wrote:
>You can't acquire the deep knowledge of an expert in the field in every
>writing job you
>approach. However, you say above that most TWs work in the software
>industry. Doesn't that make
>the knowledge of the software industry a superset of the knowledge
>required to do the job? That is, wouldn't knowledge about programming and
>the software process be transferrable among many assignments in the
>software industry--whether the domain area of these assignments was
>electronic cables or manufacuturing stockings?
You asked this of Thomas Quine, not me, but I do think that the large
number of questions specifically about programming terminology suggests
that something *might* be amiss.
Since most of us work in the software industry, we should know a lot of
software terminology, and it will indeed transfer from job to job. But the
relevant software terminology has to do with how the users see the
software, not how the programmers see it. For example, we need to know
what a "window" is, what a "field" is, and so on, not what a "local
variable" is or what "lexical scope" is.
Of course, when writing a document for programmers to read, then you need
to learn the concepts, terminology, and usage of programming. But are that
many of us writing documents for programmers to read? Or are we going
exclusively to the programmers to learn what to put in the manual, even if
it's the manual for a program that runs a machine that manufactures
stockings?
I dunno, maybe that many of us really are writing stuff for programmers to
read. But I've seen a lot of user's manuals for software that were clearly
written by someone who knew only what the programmers knew. The most
useful topic to research is the software's problem domain, not the software
itself. So I could not agree that software knowledge is a superset of the
knowledge that it takes to write a good manual. (By "most useful topic", I
don't mean "only useful topic", of course.)
I think that to write a useful manual, you need to acquire genuine
expertise yourself: in the subject matter, its language, and the people who
speak it. Only then can you intelligently judge what the manual needs to
contain. Only then can you tell what's useful and what's not, and how to
present it most usefully. Making that sort of judgement is indeed a
special tech-writer's skill. But we can't apply that skill until we've
learned the material relevant to the problem domain.
Of course we can't learn the subject in as much depth as our SMEs, but I do
think we need to know it "fairly deeply". "A little knowledge can be
dangerous", and indeed manuals written by someone with only a very
superficial understanding of the problem domain can be worse than a manual
that only describes what's on the screen. They get important stuff wrong,
they inadvertently steer users toward mistakes, and they don't have
credibility.
I find learning the subject matter the most interesting part of the job.
Well, ok, equal with figuring out how to present it. One of the main
reasons I switched from programming to tech writing, even though the latter
pays less, was that I liked the idea of acquiring in-depth knowledge of
new, esoteric subjects as part of every job--totally from scratch. I enjoy
picking people's brains and seeing what's inside. I figure that most of us
here, especially the frequent contributors, share this attitude.
So it seems a little strange that we have so many questions about usage and
format and so few about research. Or maybe there's just not that much to
say or ask about research. My suspicion is that there is a lot to say, but
what's important to know about research is the sort of knowledge that you
need to already possess in order to ask specific questions. Usage, on the
other hand, is very easy to ask questions about, perhaps because it's so
trivial. And thus we inadvertently perpetuate the myth that tech-writing
know-how is mostly knowing about spelling and typing.
