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.
Researching the subject (Was: Respect, "Returns", "Includes", "Increment", usage questions, and many more)
Subject:Researching the subject (Was: Respect, "Returns", "Includes", "Increment", usage questions, and many more) From:Ben Kovitz <apteryx -at- CHISP -dot- NET> Date:Sat, 19 Dec 1998 01:55:39 -0700
I was just looking back through my enormous accumulation of TECHWR-L
messages and noticing the large number of threads that ask for the
"correct" usage of various programming terminology.
What is going on here? Why are you asking a forum of technical writers
this sort of question?
Suppose that you were writing a manual for a telephone switch, and you came
across the term "complement". What does it mean? Can it be a verb? Can
it be an intransitive verb?
Ok, you don't know. Now who would you ask? Would you ask TECHWR-L? Would
you look it up in some official, generic, world-standard handbook of
technical writing written by people who don't know how telephones work?
Would you check the Chicago Manual of Style?
No? Good. But if you wouldn't go to tech writers to learn about telephone
networks, why are you asking tech writers about programming?
There is something much more serious going on here than just off-topic posts.
If you want to know why technical writers don't get that much respect, the
above practice is surely one of the reasons. Now, I totally agree with
Mike Huber and others that the main reason for lack of respect for
technical writers is just the huge amount of bad documentation out there.
Write good documentation and you, personally, will get respect. That might
even raise our clients' expectations for the next tech writer they hire.
But the practice of having all these esoteric, official "rules" of what is
"correct" in technical writing appears to others as little more than a
desperate search for respect. Cuz that's what it is. And for that reason,
it loses you respect. If your great contribution to a software project is
that you know the "correct" number of spaces to go after a period--well,
seriously, is there any good reason why you should be paid for that? In
that case, why *not* just hire a typist?
If you want to write good documentation, you need to research *the subject
matter*. Telling your readers useful information--giving people
knowledge--now that's worth paying for. But to give people knowledge,
first you have to get it.
You don't need to know lots of little "rules" of usage, invented by English
teachers who know nothing of what you're writing about or the people who
are going to read it. If you're writing about a copper telephone network,
then you need to know the word "complement" and how people who work in
telephony use that word.
The way you find out is to *talk to them*. Looking it up in the American
Heritage dictionary won't help. The Chicago Manual of Style doesn't count.
Those books won't tell you how *these people* use *these words* when
talking about *these things*. That is precisely what you need to find
out--first hand, by doing your own research, by acquiring genuine expertise
in the subject and the people, not by looking it up in books written by
folks who've never even heard of the community that you're writing for.
Isn't that half the fun of the job? Isn't that *half the job*?
The above rant concluded, I actually do think that it makes sense to post
questions about jargon to TECHWR-L. Since there are lots of good,
experienced tech writers here, they will have already researched all sorts
of strange fields. In this case, you're using the people here as SMEs when
your own SMEs don't even know their own subject (not so unusual). But
that's how the question should be framed: "Do any of you know about the
jargon in this particular field?", not "What is the official
English-teacher's doctrine on 'increment' as a verb?"
But this suggests that there's something else wrong. Why are all the
jargon questions about programming? You're not asking programmers about
programming as research for manuals about software that controls telephone
switches, are you?
