Re: How are technical writers perceived?

[Bruce Byfield <bbyfield -at- axionet -dot- com>]

Bonnie Granat <bgranat -at- editors-writers -dot- info> writes:

> Technical knowledge is secondary. To make technical knowledge primary 
is to not recognize that the source of amusement in "manual jokes" is the
> unprofessional writing.

Admittedly, there are jokes about poor writing, especially faulty 
translations. In fact, there are whole pages of these jokes in 
circulation on the internet.

However, in my experience, at least as many of the humorous and 
sarcastic comments about manuals (and much of the frustration) comes 
from a lack of thorough coverage of what users need to know.

Sometimes, this inadequacy is not the writer's fault. The writer is 
working from beta software, and the manual had to be finished before the 
software. Or maybe the writer was brought in late in the project, and 
didn't have the time to do a thorough job, regardless of knowledge.

But at other times, the inadequacy is probably due to the writer's lack 
of knowledge. In other words,the writer can't cover the topic throughly 
because he or she doesn't know enough. Some of the signs that lack of 
knowledge may be part of the problem are interfaced-based, rather than 
task-based organization; circular definitions of interface items, and 
subsequent revisions that do not improve on the original material.

> A technical writer is primarily a writer, not a technical expert.

A week or so ago, I argued that a writer needs technical expertise. I 
was stressing that point because it seems to me to be the part of the 
job that is most often neglected. In the context of current 
tech-writing, I think that this position is necessary as a corrective, 
and I don't apologize for it, or back down from it.

However, this week, I'd like to step back and take a broader 
perspective, Ours is a hyphenated job. It's interdisciplinary. Other 
people usually know the technology better than we do. Novelists, poets, 
and even journalists tend to write better than we do - or, probably, it 
would be more accurate to say, have more chance to strut their stuff. 
But those of us who understand the technology AND can write 
clearly,concisely, and precisely about it are a minority. To emphasize 
one side of the job over the other seriously reduces your chances of 
doing the job well.

> I further submit that those who would seek to make nontechnical 
writers feel inadequate as technical writers are those who probably 
shouldn't be in > the business.

Nobody is trying to make anyone else feel inadequate. If anyone does 
feel inadequate because of the suggestion that technical expertise is 
part of the job, then I suggest that they should ask themselves why the 
suggestion strikes a nerve. Those who know that they are doing a decent 
job of covering their material (and, I submit, anyone with at least one 
job on their resume should have at least a vague sense of the quality of 
their work) will dismiss comments like mine as not applying to them, and 
ignore them. And quite rightly so - the comments don't apply to them.

Nor are these comments directly at rush jobs, in which conditions don't 
allow your best best work. I"ve been there, and probably you have, too. 
Sometimes, delivering the job become more important than making it 
perfect, even if we don't like the fact. Judging someone's work on the 
basis of a rush job would be obviously unfair.

Nor would I insist that writers have expertise coming into a project - 
although many companies do, so this expectation is one that writers have 
to live with. You can equally well gain your expertise on the job. 
Often, too, the process of organizing material, and setting it down can 
help understanding.

However, if, by the end of a writing project, the writer doesn't have a 
reasonable level of understanding of the product and the technology 
behind it (and by "reasonable," I mean an understanding somewhat less, 
perhaps, than the developers', but at least enough to understand most of 
their discussions, ask intelligent questions and to have a keen 
suspicion when given information that's wonky) - then the odds are going 
to be very high that the resulting documentation is inadequate.

You can't fake expertise, no matter how well you write. The moment that 
end-users try to use a doc which the writer bluffed his or her way 
through, the problems with it are going to be exposed.

--
Bruce Byfield 604.421.7177 bbyfield -at- axionet -dot- com

"The following morning, the headlines were tall,
'Really, it was inevitable,
Mr. Dumpty was drunk when he fell from the wall,
He was already cracked, and shell-shocked and all.'"
- Tommy Sands, "Humpty Dumpty Was Pushed"





^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check it out! Get some cool freebies when you buy RoboHelp! You'll receive
SnagIt screen capture software and a 10% discount voucher for RoboHelp
Consulting. This special offers expires March 29, 2002.
www.ehelp.com/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.