Re: How are technical writers perceived?

Subject: Re: How are technical writers perceived?
From: Bruce Byfield <bbyfield -at- axionet -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sat, 16 Mar 2002 18:32:39 -0800

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.

Have you looked at the new content on TECHWR-L lately?
See 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 for more resources and info.


Previous by Author: Re: How are Technical Writer's Perceived
Next by Author: Re: How are technical writers perceived?
Previous by Thread: Re: How are technical writers perceived?
Next by Thread: Re: How are technical writers perceived?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads