Re: STC Letter to the Editor

[Andrew Plato <gilliankitty -at- yahoo -dot- com>]

<eric -dot- dunn -at- ca -dot- transport -dot- bombardier -dot- com> wrote ...

> Indeed a "Technical Writer" or "Technical Communicator" is defined by their
> technical knowledge. But to argue the level of technical knowledge required by
> that communicator/writer in an open forum is a red herring (and let's face it
> this 'discussion' is just another tired rehash of "tech writers aren't
technical
> enough"). Anyone who engages in such discussion is really just wasting their
> time unless they are discussing the requirements for one particular product in
> one industry and for the same audience.

So the only way we can discuss content issues is if we have a specific subject in
mind? I disagree. Content, as a concept, permeates all subjects. Just because
you're writing about Wal-Mart procedures (to pull an example mentioned earlier)
doesn't mean the content is any more or less important and doesn't mean we can't
insist on excellence in content. 

> So how do you improve your work? How do you judge your work against that of
> others? How can you share the lessons you have learned with others in your
> trade? Well, you create an organization that tries to cover the common ground.
> You discuss the generalities of audience analysis, how to limit rework, how
best
> to extract information from SMEs and organize it, how best to publish and
> deliver the documents, how best to manage resources. I've only been to one STC
> meeting. But nobody there, and nobody on this list has ever IME said that
> presentation, process, grammar, screenshot methods, tool use, or anything else
> should be the first consideration above technical content and accuracy. 

You're right - nobody will come out and directly say that, because it is
flamingly wrong. Where my issue lies is in an assessment of priorities.

1. The community agrees, content is paramount. Yay!

2. The community gathers and spends most of their time discussing everything -
except content. Huh? 

One has to wonder about the priorities of a community when the issue of paramount
importance is relegated behind issues of marginal importance. 

The downside of this is that the tech writing community has a large contingent of
writers who are sitting in tech writing jobs playing with styles and fonts all
day convinced they are accomplished authors because STC tells them that this is
what a writer does. 

These people bounce from job to job, obsessing over fonts and single-sourcing
while STC cheers them on. Nobody steps in front of them to say - did it ever
occur to you that fonts and styles are really not that important? 

> That leads to the question of how do you judge the work of writers in diverse
> fields of expertise? 

You judge them by how well people like and consume the work. If that isn't
possible, then you make it clear that you ARE judging by superficial aspects -
like style and presentation. 

> Perhaps it isn't worthwhile. But if you are going to do it,
> first you make the assumption that the manuals ARE written accurately and the
> writer IS knowledgeable about their industry. 

NO! That is like assuming the gun isn't loaded, pointing at your head, and
pulling the trigger. You NEVER assume that the manuals are accurate. Because
accuracy is the crux issue. 

This assumption is what has lead the writing world to what it is today - reams
and reams of utterly worthless documentation. 

> You then look at the presentation,
> organization, and usability of the document. Arguments against STC, saying
> technical writers aren't technical enough, process is a waste of time,
> formatting/design are irrelevant all have a common base
> argument/assumption/prejudice. That writers are incompetent whiners out to
screw
> management for all the money they can get. 

This may be the view you want to see, but it isn't the view I express. I see a
lot of writers mislead and miseducated. They are told over and over again that
they don't need to be technical. That content is somebody else's problem. This is
compounded with a general lack of interest in documentation. The two form a
vicious circle. The more writers ignore content issues, the more management loses
interest in documentation issues. 

> This is a  poor jaundiced view that
> insults the profession and the members of the list. Indeed I find it highly
> unprofessional to base commentary on such a view in a forum that is full of
> people you do not know and therefore are in a poor position to judge.

I don't know what others I doing, but I base my judgments on the technical
manuals I read each and every day. Some are good, but most suck ass. And that is
my criteria. Who wrote them is unimportant to me. All I know is that the ones
that suck ass are clearly written by folks that don't know what they're talking
about. 

And why is it that so many manuals suck ass? 

1. Writers don't take the time to make them interesting.
2. Management doesn't give them the time. 

Those two factors are another part of the vicious circle. The more you relegate
content issues, the less management cares about your work. 

> There is a minimum level of technical information, organization, design, and
> process required to produce usable documentation.

There is? Who decides what that minimum level is? As I have said 1000 times now,
some of the most important information I've ever read came out of a homely text
file. A file that gave me EXACTLY what I wanted, yet would have lost every STC
competition it was ever entered. 

So, on one hand we have a homely text file that did exactly what it was supposed
to do - communicate information to a reader. And on the other hand we have this
mysterious minimum level of acceptability that STC has established which would
have kicked out a document that did its job perfectly? 

Huh? 

Now, if the STC competition was on style and layout, well then I can certainly
understand why a homely text file would lose. The information in the file wasn't
being judged, just the external beauty. In that case, STC can make up whatever
criteria it wants, since its judging beauty, no content. 

> Also, the "writer/communicator" part of our job title should be able to be
> judged. I fail to see why it shouldn't be possible to write a document that
> describes a totally fictitious system and its operation and submit it to the
> STC. Even without the actual product, it SHOULD be possible to judge if the
> document is clear, concise, and effectively communicates the information to the
> fictitious user.

How? if you don't know the product, the technology, or its use how do you know if
the right information is being delivered concisely. 

1. Flush the ARP cache if there are resolution problems on the firewall. 

vs.

2. When new items are added or changed on the network, it may temporarily cause
resolution problems at the network gateway. If the firewall is being used as your
network gateway, it may become necessary to flush the ARP cache. This cache keeps
track of the physical or MAC address of all the devices on the network.

Arguably 1 is way more concise. But it also has a misleading element. Name
resolution is a bigger issue than merely the firewall. Moreover, if the firewall
isn't being used as a gateway, then #1 is bordering on inaccurate. 

Merely being concise and clear, is not synonymous with being accurate. Accuracy
is a complex problem that is not easily evaluated. 

This is why most STC winners are of dubious honor. Nobody of expertise has read
through the material and objectively said "yeah, this really communicates this
product/technology with exceptionally accuracy and insight."  Hence, you are not
really analyzing the communication, but just the presentation. And therefore,
judgments of conciseness or clarity are virtually meaningless. 

Consider one more example:

- The sky is green.

About as clear as it gets, concise too. Totally wrong. According to STC
guidelines, this nugget of wisdom would be an award winner, because we're
assuming that the content - a green sky - is correct. 

> <<Simple goals like "does this accurately communicate these concepts" are
> sufficient.>>
> Which while nice is a simplistic view of the exercise. The above goal has only
a
> yes/no answer. It would be impossible to judge a competition under that
standard
> alone. So for all those who have a beef with the contest, then what are the
> further considerations? And how about assuming a couple of positive things
> first? For one, unless you find inconsistencies assume that the document IS
> technically accurate. Secondly, there is absolutely NO need for the product to
> be present. Assume the product works exactly as documented.

Assume all you want, I demand proof. I don't just assume the gun ain't loaded and
wave it around. I don't just assume those friendly people in Nigeria really want
to send me 30 million dollars. I don't assume that data is correct. 

In ALL scientific endeavors, data (information) must be proven to be consider
legitimate. If the data can't be proven, then there is no way to objectively
evaluate its value. 

Andrew Plato 

__________________________________________________
Do you Yahoo!?
HotJobs - Search new jobs daily now
http://hotjobs.yahoo.com/


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All-new RoboHelp X3 is now shipping! Get single sourcing, print-quality
documentation, conditional text and much more, in the most monumental
release ever. Save $100! Order online at http://www.ehelp.com/techwr-l

Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!

---
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.