Re: Article: "Living Documentation"

Subject: Re: Article: "Living Documentation"
From: Jeff Hanvey <jewahe -at- lycos -dot- co -dot- uk>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 04 Apr 2003 21:34:28 -0500

On Fri, 4 Apr 2003 15:06:42 -0800 (PST), Andrew Plato:

It's not that I'm necessarily attacking you, but that I'm attacking your stubborn insistance that all of us are just inept, stupid hacks out there ruining documentation by worrying more about fonts, templates, and grammar than actually developing content. That's simply not true - and I think this list tends to highlights those things simply because those are the things that we most have in common.

It simply irks me that you put forth the attitude, at least on list, that *all* tech writers aren't professional, because they don't take responsibility for mistakes. Your experiences may have proven this out, but mine have not. Every writer - every worker I've been around has been more than willing to determine what went wrong and what can be done to avoid that problem in the future. Those who played blame games and weren't productive didn't stay very long. Maybe that's just the luck of my draw, but I've never been a place where people played more than they worked - I've always been around professional people who took their jobs seriously (okay, so that wasn't true of my high school and grad school Pizza Hut days).

What I find most often in your attitude is a disconnect between the real world and your world. You work in an environment where you *can* control every bit of the process and ther results. For those who own their own business or do consulting work, they pretty much get to make their own rules and work within their own guidelines to produce the finished product.

However, most of us DON'T. We work in an environment where we have to do what other people tell us to do, where we have to shunt aside our personal feelings and biases and do the job the way we're told to do.

Many of us who work in that real world deal with an environment where communication is not a priority, and where people have carved their own little territories and feel that letting people into that territory is going to carve into their power base. I deal with this all the time - there are programmers in my own company who for their very lives have no idea why things are *not* self evident and who treat even the simplest question like it is the most ridiculous thing they've every heard. And I don't bother them with questions - I take the time to delve into the source code, to read whatever I can, to get my hands on the software. I only ask the question when I've exhausted all my sources.

To the point to technical knowledge, it never seems to occur to you that it really isn't the training and certifications that are important, but the person's willingness to *continue* training, to take the impetus and get his hands dirty. Every technical person I know has not learned much out of books, but from having contact with the real thing - and from dealing with real-world situations.

Excuses, excuses, excuses. "We didn't get access and therefore we couldn't do
good work." Bah. Its a writer's responsibility to get the information they
need, by hook or by crook.

This is *not* an excuse, and shows again that disconnect between your world and our world. I have repeatedly requested access - but the code is so tightly controlled in our environment during development that only the programmers and a few high-level managers. My supervisor doesn't even have access to the code.

Live in the real world a few day, Plato, and you'll get a major surprise.

And this is exactly the type of bashing inherent in your attitude - I'm just a hack because I have to work within the system to do my job. I can't force the change, although I do make recommendations, and am *very* vocal about things that aren't working, and questioning why things are the way they are. I feel very strongly that my job is to be an advocate for my user group - and that things have to make sense to them. Our organization is very programming-centered, and things are coded in such a way to make their jobs and lives easier, not the users, who are paying us a boatload of money to use our software. We're slowly making inroads into the attitude, and things are changing for the better.

There are going to be errors in our documentation. We are dealing with a legacy system, as well as one of the inept writers you are so frequently fond of bringing up (this writer was so bad, she refused to learn to use FrameMaker efficiently, and our docs were a mishmash of Word and Frame stuff. The customer support group would frequently tell users not to refer to the documents because they were just plain wrong. Yes, that was her fault, because she didn't want to learn the system. It was also the company's fault for allowing the situation to go on for so long that documentation was just a joke - when the company got sued because someone used to documentation with a resulting *huge* cash loss due to incorrect interest calculations (these are banks), the documentation and Q/A team was immediately reorganized).

But I take great pride in my job, and am constantly questioning *everything,* constantly working to improve it to be usable - with a receptive manager who has already done a tremendous amount of work improving the docs, we are turning things around. We work hard to stay on top of development, and do not produce crappy documentation. The problem is that chasing down updates leaves us little time to update those things that rarely change (that is actually my current project, fleshing out many of the older docs, especially our reports).

That's why I take offense at your generalizations - it lumps everyone together into the bad, and that does no one any good - and, more importantly, does nothing to improve the view of others towards technical writers. If you are so disdainful, and you're labeling yourself as a writer, then that attitude will be transferred to those outside the profession. And that's why I am vocal about disagreeing with you.

Jeff Hanvey
jewahe -at- lycos -dot- co -dot- uk
Augusta, GA

Purchase RoboHelp X3 in April and receive a $100 mail-in rebate, plus FREE RoboScreenCapture and WebHelp Merge Module. Order here:

Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at
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 for more resources and info.


Re: Article: "Living Documentation": From: Andrew Plato

Previous by Author: Re: Article: "Living Documentation"
Next by Author: Re: Who is responsible? (was living doc article)
Previous by Thread: Re: Article: "Living Documentation"
Next by Thread: Re: Article: "Living Documentation"

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

Sponsored Ads

Sponsored Ads