Re: I'm taking my marbles and going home...

Subject: Re: I'm taking my marbles and going home...
From: Bruce Byfield <bbyfield -at- axionet -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 13 Aug 2002 12:33:31 -0700

Martin R. Soderstrom wrote:

> You're being obtuse.

No, I was responding to what you actually wrote. However, you clarified what you meant, so thanks..

Finally, how can too much knowledge be a hindrance? You don't write API
documentation for clerical staff.

Again, I didn't say that.

Actually, you did:

"Sure, you're going to need some basic understanding of
technologies and practices, but no where near the depth to which an actual programmer would. In fact, that can be a hindrance."

But, again, thanks for the clarification.

(BTW - I introduced clerical staff as the polar opposite of an audience of programmers.The point is, of course, that if you make assumptions of knowledge in an API document, the chances are that those assumptions are valid for your audience).

I said that years of doing the same thing puts
you at an experience level on that subject where it is impossible to
identify with someone new to the technology.

I disagree with that "impossible." Good tech-writers need to be able to anticipate the needs of new users. That can be done by usability testing of documentation, but it can also be done to a large extent by the right combination of intelligence and imagination. In fact, given that many companies don't do any sort of usability testing for documentation, usually that empathic ability is all that you have to work with.

I've found that there are as many ways to write as there are writers, so if
your way works for you, that's wonderful. But if you believe that your way
is the only way, I've got some communist manifestos you might be interested
in. :)

As opposed to the open-mindedness of doctrinaire conservatives, right? ;-)

But it's not just a matter of individual quirks (although I have those to spare). What I'm really saying is that you need to understand the content to write well. No matter what your quirks, I don't see any way around that necessity. If you muddle through without a reasonable understanding, you can produce something, and it might even be considered acceptable by your employer or clients - but it won't be as useful as equivalent work done with understanding.

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

"A story untold could be the one that kills you."
- Pat Conroy, "Beach Music"

Want to support TECHWR-L? Get shirts, bags, hats, clocks,
and more from the TECHWR-L Store. All proceeds support TECHWR-L.

Save up to 50% with RoboHelp Deluxe. Get 2 great products for 1 low price!
You'll get RoboHelp Office PLUS RoboDemo, the software demonstration tool
that everyone's been talking about. Check it out and save!

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: Technical editing vs. technical writing?
Next by Author: Re: I'm taking my marbles and going home...
Previous by Thread: Re: I'm taking my marbles and going home...
Next by Thread: Re: I'm taking my marbles and going home...

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

Sponsored Ads

Sponsored Ads