Re: STC Letter to the Editor

[eric -dot- dunn -at- ca -dot- transport -dot- bombardier -dot- com]

Once again a lot of noise over nothing. Yes technical accuracy is paramount in a
technical manual. And, yes a pretty box of shit is just a box of shit. But the
most accurate and well explained procedures placed in a box of shit are ....

Well, I'd think it would be little more useful than the aforementioned excrement
receptacle. So all the technical accuracy in the world isn't going to help your
reader if they can't access and comprehend the information. All the engineering
documents most of us see in the process of doing our jobs are technically
accurate, so why on earth don't we just give the users those? If the only judge
of a technical manual is its accuracy, then Tech writers are a waste of time and
money and we should just QA the Engineering documentation to correct ant
inaccuracies.

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 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
can't exactly question anybody other than a colleague at work as to how a thing
works can you? If I asked on this list about the functioning of IGBT propulsion
units or track side signaling I doubt I'd get any useful answers.

That leads to the question of how do you judge the work of writers in diverse
fields of expertise? 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. 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 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 therefor are in a poor position to judge.

There is a minimum level of technical information, organization, design, and
process required to produce usable documentation. On that base you can improve
the design, layout, organization, and usability. You can make it more pleasant
to read and use graphic and art pretty it up. There is a point of diminishing
returns of course. Where an improvement to the design adds little or nothing
measurable to the document. There is also a point a which fussing with the
design any more may impede understanding and clarity.

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.

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

Best quote yet from the show "The White House": 'Very few issues are black and
white. And of those that are, most involve body counts.'

Eric L. Dunn




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