RE: Technical Documentation solutions?

Subject: RE: Technical Documentation solutions?
From: "Sean Brierley" <sbri -at- haestad -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 27 Aug 2002 13:33:11 -0400

While I appreciate the questions and thoughts, and desire, I disagree
with your assessment of documentation and tech writers as a whole. I
disagree that you can have programmers and other SMEs do documentation
and that such documentation chore would be something they wanted to do
and something that did not affect their schedule. I disagree that there
are not technical writers out there who are capable of writing about
code, or APIs, and the like.

-----Original Message-----
From: Manley Clifford (GFD1CEM)

I is serious as a heart attack.

>I have been a Technical Writer and Business Analyst in many IS/IT
environments for over twenty-three years. I have watched my brethren
build, implement and walk away from every sort of failed documentation

But, you expect to do all of this in 6 months and have the process be
self-sufficient when you walk away?

>I have watched corporations hire flocks of TWs to be documentation

That sounds off. Most should hire TWs to be authors and writers.

>I have watched an entire industry of tech writers come to life,
busily perpetuating the status quo.

Like single sourcing? Like moving docs online away from printed output?
What is the status quo? You mention printed docs being static and
automatically out of date, but online docs, XML, and the like are also
if their content is not maintained.

>I have watched an entire industry of
content management and document repositories come alive - and it's all a
false prophecy.

Well . . . I've not seen content management and document repositories
work, but the folks at Documentum and other places might have a
different opinion.

>None of it - not one company in this world - can say with an honest
that their documentation is Accurate, Usable and Cost-Effective.

Nuts. Of course they can, and they do. How are you measuring and
defining those things? That's like saying programming is not accurate,
usable, and cost effective because there is labor involved in it and
there are bugs and, sometimes, you can't start up and run with the
application without reading the doc first.

>I cannot
walk into a single IT shop and ask at random for a document and watch
find it easily and assure me that I can trust it.

You can. Right here. And, many other places. It's as hard as walking
into a programming shop and asking for the source files. Whoooop, there
it is!

>Bits and pieces. Whatever was burning last month. Those are the docs
might be found and may be current.

Not so.

>I think it's time we stopped doing what we have always done and
different results.
>You do what you always have and you'll get what you always got.

Certainly not true. For example, my docs get done more accurately and
more rapidly, with less labor than ever before. And, because I can ship
online, also, they are more accurate, with changes going out with a
patch, etc.

>I am one who is ready for a sea change in how documentation is done.

I think you are one who has worked in some truly chaotic hellish
documentation environments. Is UPS that way? Ick.

Yours in cheerful disagreement (but I do look forward to you posting in
6 months to tell us of your successes, failures, and things you learnt
along the way).


Want to support TECHWR-L? Get shirts, bags, hats, clocks,
and more from the TECHWR-L Store. All proceeds support TECHWR-L.

Check out the new release of RoboDemo, our easy-to-use tutorial software.
Plus, buy RoboHelp Office in August and save $100 with our mail-in rebate.
Get details and download free trial versions at

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 for more resources and info.

Previous by Author: RE: Technical Documentation solutions?
Next by Author: RE: Technical Documentation solutions?
Previous by Thread: RE: Technical Documentation solutions?
Next by Thread: RE: Technical Documentation solutions?

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

Sponsored Ads