Teacher---Andrew hurt my feelings! (longish)

["Samuel Choy" <schoy -at- us -dot- ibm -dot- com>]

Sorry to chime in so late on this thread--I've up to my earlobes in
documenting C header files. Yuck.

Andrew Plato writes:

You'd be right about one thing. I should have said "inaccuracies are 100%
the
direct *responsibility* of the authors and editors and 99% of the time it
is
because the authors don't understand the material.
-----------------------------------------

I've been thinking about why this phrase has gotten so many people upset. I
don't think its the "responsibility" part, but the "authors don't
understand the material" part.

Some are interpreting that to mean that  Andrew thinks 99% of technical
writers are incompetent or lazy and taking it as a personal insult. Whether
or not Andrew thinks that 99% of tech writers are incompetent or lazy is
irrelevant to the discussion. I don't mean any disrespect to Andrew, but
what does it matter what  he thinks about me? I really doubt he had me
personally in mind when he wrote that. Let's put personal feelings aside
and evaluate the statement "authors don't understand the material."

Let look at the different  levels of error that can happen in technical
documentation, and what those errors show about the author's knowledge of
the material. And I don't mean errors that are caused by updates to the
product occurring after the book is published.

1. Grammar, typo, pagination, stylistic errors. - Obviously this is the
writer and editor's fault. These might not make the book look very
professional, but if the errors don't change the technical meaning of the
content, then those are inconsequential.  Those errors say nothing about
the knowledge level of the author.

2.  Sporadic, minor,  technical errors. For example, a 200 page book is
published and  there are two technical errors in the book..  The only
reason that the author could have made those two errors was if he or she
had a misunderstanding that material.  I can't see how there could be any
other explanation. Even if the author was also an SME on the topic, those
two errors were made because the author had a misunderstanding of those
concepts.

3. Complete mess. I will give a real life example. About two years ago I
purchased some music editing software. To this day I have not been able to
figure out what most of it does. The help and the manual are completely
worthless. First of all, the manual is just a printed version of the help.
They tell you how to get to each function of the software through the
pull-down menus. But the documentation does not tell you what the function
does or why you would use it. I would say that in that case the writer
seems to have a complete misunderstanding of the software. Yes, I know,
there might have been managerial mandates on the length of the book, and
all sorts of other things out of the writer's control. But even so, if the
author new what he was writing about, there would be more evidence of it in
the book.

And now I will give a personal example. The stuff I write is fairly complex
and very conceptual. On top of that, my topic covers a wide array of other
subtopics. For each sub topic, I have a different developer as a reviewer.
I would classify my reviewers' knowledge as very deep in there own area of
knowledge, but  also very narrow. When I have a question for a reviewer
that strays out of their area of knowledge, they refer me to another
developer. And sometimes during my reviews, the reviewers argue amongst
themselves about what is indeed technically correct. Needless to say, I
have made some technical errors  in my documentation that were published.
And I have to say that those errors were because, my knowledge at the time
was wrong. How else could those errors have gotten there? Gremlins? That
doesn't mean I'm incompetent, or an idiot, or anything else. Nevertheless,
I am responsible for those errors.

But admitting those errors and learning from them makes me a better and
more knowledgeable writer.

Andrew can say things in a way that irks the heck out of me sometimes. And
as it has been said of him before,  he often he is the one shouting the
emperor has no clothes.

Samuel Choy
IBM Rochester
http://www.ibm.com/eserver/iseries/infocenter

My opinions are mine and not IBM's.



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Purchase RoboHelp X3 in April and receive a $100 mail-in 
rebate, plus FREE RoboScreenCapture and WebHelp Merge Module.  
Order here: http://www.ehelp.com/products/robohelp/


   Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at http://www.raycomm.com/techwhirl/special/contests/
Happy birthday to you, happy birthday to you, happy birthday TECHWR-L....

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