Re: 'Old fashioned' Tech Writers

Subject: Re: 'Old fashioned' Tech Writers
From: Dick Margulis <margulisd -at- comcast -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sun, 11 Jul 2004 10:59:42 -0400

That's all well and good, John. But it gets complicated sometimes.

Say you have an application that might be used by a thousand people in one company. Well, it's worth the investment to go learn as much as you can about how the people in that one company do their jobs.

And the same application, with some configuration options set differently, might be used by a thousand people in a second company. And the way people in that company do their jobs (or even the level of computer literacy in that second company) might be substantially different from the situation in the first company.

Now add a third and a fourth a fiftieth and a hundredth company, all with slightly or radically different audience characteristics.

But you have to document the application for the benefit of users you cannot possibly know about yet, back when you're writing help for the first company.

We can make certain assumptions about our users, and then we can revisit those assumptions later if circumstances dictate. Or we can write enormously more complex documentation, with conditional text tied to the configuration options set in the application, if we're willing to spend the time and money it takes to do that.

But what we cannot do, for most products, is know with any degree of certainty who the audience is going to turn out to be, at least not before the product is on the market for a while. Nor can we easily apply some formula that tells us we're meeting the needs of the majority of our audience. I'm not by any means saying we can't meet the needs of the audience; writers do it all the time. I'm just saying that the writer's experience, judgment, empathy for the reader, skill with language, and willingness to revisit assumptions over time will get you a lot closer to your goal than methodology alone ever will.

Does this mean that sometimes you include information about edge cases? Does it mean that sometimes the software itself should accommodate those edge cases? Maybe. It depends on the circumstances. If you can afford to ignore outliers as potential customers, great. If you can retrain those outliers to do their jobs the way other people in the same industry do them, great. If not, maybe you accommodate them, given a large enough potential sale.

I'm all in favor of making tech writing as simple and formulaic and mechanistic as it can be--so long as it is still effective. But there has to be a writer in the loop, too, who can apply judgment (call it experience-meditated intuition if you like) and skill, too.

John Posada wrote:

The mantra we hear over an over again in tech writing is "Write for
your audience. Write for your audience." Yet, as soon as an effort is
made to exclude a category of user because they "might" be an
audience even though they haven't been identified, or refuse to write
about a feature with which only 1 out of 100 users "might" do
something some way, then we scream bloody murder.

What do you think "write for your audience" means? To me, it means.
don't write for someone who ISN'T your audience.

How do we do that. Maybe you need to study the target marketplace and
figure out who that user is? I can't speak for all companies, but we
spent MORE than a full year interviewing and observing a substantial
number of potential users to identify who that user is before writing
one line of code. don't do this by seeing how they use your existing software
and modify it for the user...I saying you do this from the ground up.
How do they do their job, then you design the application to help
them do it.


ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!

WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed!
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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.


Re: 'Old fashioned' Tech Writers: From: John Posada

Previous by Author: Re: 'Old fashioned' Tech Writers
Next by Author: Re: STC Transformation -- info
Previous by Thread: Re: 'Old fashioned' Tech Writers
Next by Thread: Re: 'Old fashioned' Tech Writers

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

Sponsored Ads