Re: Researching your Subject

[Ben Kovitz <apteryx -at- CHISP -dot- NET>]

Thomas Quine wrote:

>Ben Kovitz posted a lengthy rant (which I mercifully will not reproduce
>here) making the point that discussing the correct use of programming
>terms is inappropriate for this list.
>
>That's foolish. Most of us are in the software industry, and usage is
>central to our occupations.
>
>Ben goes on to argue that it's our responsibility not to trouble the
>list with such questions, but to "research the subject" and "acquire
>genuine expertise" in it.

What??  I don't recall saying that people shouldn't ask these questions of
the list.  In fact, at the end of the message, I said that the list can be
a good resource for that sort of thing.  (In general, I don't post messages
telling people that certain topics are inappropriate for the list.)

The rant was about being concerned about "correctness", in a totally
generic sense, such as what the Chicago Manual of Style covers, over the
specific subject matter and speech community that we're writing for.

I was criticizing the attitude that objects to the way programmers use the
word "increment" (as a verb) because the OED or your high-school English
teacher says that it's "incorrect" to use it that way.  And I was saying
that acquiring genuine expertise in the subject matter, its language, and
the people who use it should be half the job.  Being good at that is (half
of) what makes you a good technical writer, not knowing theology like the
"correct" number of spaces to go after a period.  And isn't it half the
fun, too?

Perhaps my name got attached to some other message?

>Two years ago I wrote an excellent manual about cable installation which
>my client was very pleased with and paid handsomely for. This year, I
>can't tell you a thing about cable installation. Because my job was to
>capture the knowledge of the SMEs and present it in the most accessible
>and user-friendly format - not to install cable. I'm a professional
>technical communicator - I'd never cut it as a cable guy, and don't even
>want to try.
>
>Of course, if I were carving out a career in the cable industry, I would
>be wise to build up some expertise in the field. Instead I concentrated
>on sharpening my interviewing skills, my communication skills, my layout
>and illustration skills, my project management skills, all of which
>serve my career and make me more valuable to my next employer.
>
>What I retain is what is relevant to my own area of expertise, namely
>the craft of technical writing.
>
>I firmly believe a skilled technical writer or skilled instructional
>designer can teach anyone anything, even about a subject they've never
>been exposed to before the project commences. That's where our expertise
>should lie...

We agree, of course.  And it sounds like you do exactly what I am proposing
that all tech writers do: learn *the subject* as part of the job.  And yes,
you learn it from SMEs, you don't necessarily retain it after the job, and
you don't learn it in as much depth or detail as the SMEs have.

I get the impression from a lot of questions posted to the list that many
people go at tech writing with the opposite attitude, though.  I'm not
saying not to post the questions, though!  I'm saying there's something
wrong when people think "knowing the answers to these questions is what
makes a person a good technical writer."

Well, I don't get this impression just from the list, I get it from a lot
of direct observation.  Surely you've come across tech writers who think
like this: "I put all the screens and field descriptions into the 'correct'
layout according to the 'official' rules, therefore I did a professional
job.  And I deserve lots of respect and pay 'cuz I know all these esoterica
of technical writing that no one else does."

I've seen lots of these technical writers gleefully write and format
everything "correctly" and produce a completely worthless manual.  That's
because all it says is what any moron could tell for himself just by
looking at the screens.  In other words, when manuals are useless, it's
usually because the writer skipped the, er, subject of my message:
researching the subject.

They're *really* useless when the writer imposes rules from other speech
communities, like substituting "retrieves" for "returns", over the
conventions and concepts of the subject matter--the very mistake that
people are asking for our help in making.

--
Ben Kovitz <apteryx -at- chisp -dot- net>
Boulder, Colorado


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=