Re: 'Old fashioned' Tech Writers

[Dick Margulis <margulisd -at- comcast -dot- net>]

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: