Re: Article: "Living Documentation"

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

"Jeff Hanvey" <jewahe -at- lycos -dot- co -dot- uk> wrote in message news:193278 -at- techwr-l -dot-  -dot-  -dot- 
> 
> 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. 

When have I ever said that "all of you" are stupid hacks? Never, not once. 

I attack behaviors and concepts. I don't attack individuals. 

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

No. Technical writers who don't take responsibility for their work are
unprofessional.

There are plenty of writers, right here on TECHWR-L, who understand what it
means to take responsibility for their work. These people consistently produce
good work, get good jobs, and are (in my mind) worthy of professional respect. 

When these professionals make a mistake, they fess up to it, take
responsibility, and immediately work toward fixing it. They don't instantly
slip into CYA whine mode where they blame the SME, their manager, or the lack
of respect they get as reasons for why they screwed up. 

I'd even say, that in cases when it probably IS somebody else's fault, a real
professional doesn't care. They are more concerned with making wrongs right,
not blaming others. 

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

That's not true even a little bit. I have demanding customers who are worse
than managers. Unlike many folks on the list, who have a nice pretty paycheck
at the end of each week and other comfy little perks, my ability to make money
is DIRECTLY related to my ability to make customers happy. If I make a mistake
and anger customers, I'm out the door living off Top Ramen. I don't have the
luxury of dawdling around waiting for approval from above. When the hammer
comes down, my customers expect me (and my team) to make it happen.

In many cases I have X number of hours to make Y happen. And failure isn't an
option. 

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

Jeez, then why do you work at these slave factories.

This is becoming more a discussion of temperament then professionalism. How a
personal handles their work environment has a lot to do with the type of jobs
they get and the respect they earn. 

If I were to lay this on a spectrum using soldiers as a metaphor, I would say
at one end are the "grunts."  People who don't do anything unless they are
ordered to do it. Like the front line infantry guy. 

On the other end of that spectrum are mercenaries. People who operate almost
entirely on their own behalf. They aren't given orders so much as vague
projects.  

In the middle are generals and leaders. They have orders and rules to follow,
but mostly can fill in a lot of the details. 

Generally, people who wait for approval to do something wind up in
lower-respect, lower-risk, lower-pay jobs. These places, in general, will
tolerate writers who blame others and shirk responsibility. It goes with the
territory. The less respect/money there is in a job, generally the less
competent and self-directed you are expected to be. 

At the other side, people who make things happen and forge ahead in the face of
adversity, tend to wind up in higher-respect, higher-pay, higher-risk jobs.
Again, it goes with the territory, the more risk you take the greater the
rewards. 

This isn't a perfect system, but it works. 

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

And I don't blame those engineers. They have spent years learning technology
and a skill. Its not their job to play teacher to tech writers. 

Again, this is a personal temperament issue. If you walk in the door with a
sheepish, "please be my friend" look on your face begging for approval - people
will treat you like crap. If you walk in with some authority and force behind
you, people will take notice and respect you. And this is not a "nice guy vs.
jerk" decision. You can be demanding, forceful, and forthright without being a
jerk. 

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

Why do you need the code? Don't you have the software? Do you really need to be
picking through the code? 

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

No need to insult me, Jeff.  I live in the real world. And I have been EXACTLY
where you are many, many times. Just because I disagree with your ideas doesn't
mean I am cut off from the world. We see the world differently, Jeff. 

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

Great, but how you do all that is more important than doing it. I've watched
plenty of fire-in-the-belly writers strut into a development team and start
demanding this, that, and the other thing. They are quickly shut out of the
team, ignored, and cut off from information to wither and die. Like any
community, you have to lurk for a while. Learn the lay of the land. Only when
you've learned the customs and language of a community can you start making
suggestions and integrating with those people. 

> I feel very strongly that my job is to be an advocate for my user 
> group

Why you? 

Are you an expert user of the products? Do you talk regularly with actual
users? Have you been out in the field installing, managing, and maintaining
this technology? Have you sat in on support issues? Do you really know what
your users do? What is their business? What is the place of that business in
the market? Is that industry making money? What is hot in that industry? Who
are the leaders? What is your company's position in that market? How is the
product being marketed? etc. etc. etc. 

Before you can be an "advocate for the user" you had damn well understand the
entire scope of the market, technology, and customers you serve. Arguing over
the position of radio buttons and checkboxes isn't being an "advocate for the
user." Its assuming responsibility that very well might not be yours to take. 

I don't expect you to answer my questions, just think about what I am saying.  

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

Why don't you make it your personal responsibility to see that doesn't happen.

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

Great. Stop trying to justify yourself to me Jeff. You don't need my approval.
Don't take my arguments so personally. 

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

No...YOU have lumped everybody together under my argument. Not me. And I am not
responsible for your interpretation of my argument. 

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

I am not disdainful of all writers - just a segment of the tech writer world. 
A vocal, misinformed, gaggle of writers who fondle-fonts, obsess over
processes, you know - THEM.

It always amazes me how technical writers are so desperate for professional
respect, yet they adamantly refuse to do what it takes to earn that respect. My
position then is - if you want respect, take responsibility. Make it your
personal responsibility to ensure the docs are top notch, with no errors. When
errors are made, stand up and take responsibility and vow to fix it. 

Will errors happen - of course. Don't be a baby about it, take responsibility
and fix it. Even  if it wasn't technically your fault. The docs are your
responsibility, take responsibility for the content. 

Andrew Plato 


__________________________________________________
Do you Yahoo!?
Yahoo! Tax Center - File online, calculators, forms, and more
http://tax.yahoo.com

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