Re: Development/Documentation

Subject: Re: Development/Documentation
From: "Lisa Wright" <liwright -at- qwest -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 5 Feb 2001 23:21:29 -0700

Lisa Miller said:
"The tug-of-war stems in my opinion stems from an
erroneous view by members of development that documentation is subordinate
the development project. This belief is demonstrated by development feeling
comfortable with trying to define content, some design, and placing
on how documentation will be developed (i.e. meeting with users, what tasks
appropriate, and so on). "

I've been thinking about this issue, in a generalized way, recently because
we do see so many complaints about development or marketing or whomever
telling technical writers what to do, and I've wondered why I'm not always
up in arms and feeling under attack. Is something wrong with me? Maybe I'm
not a real tech writer! Why didn't I have a conniption fit when they told me
I had to use Word??? I've really only once worked with a developer who acted
as if I wasn't worth spit and discovered it was because he 1. hadn't ever
worked with a technical writer and 2. didn't comprehend that I was his peer
and he's very status oriented. He now understands the error of his ways. :-)

I think whether others treat your job dismissively is largely one of
attitude. If you project a peer attitude instead of that of the poor
barefooted step-child, your developers may quit behaving as if your tasks
are subordinate to theirs. I have worked for a lot of control freaks and
contracted for one woman who loved being a bully. I don't walk around
looking for permission to do the job I was hired to do, nor do I look for
approval for all my actions, and I never let that woman bully me. Because
people know that I won't back down and that I can back up my reasons, I tend
not to get stepped on. This occasionally bites me in the *&$#, but I'm still
good at what I do. I filter things with the attitude that I am the expert,
and that I have good, flexible skills.

You are the expert. If you are not totally confident about countering head
on a suggestion when you don't like it, come up with some phrase that tells
the person, "okay, I'm paying attention to what you're saying," but avoid
committing until you can find some backing for *why* you don't want to do
something. Read lots. Observe. Pay attention to the vocabulary the person is
using so you know what's important to them. I work with a marketing person
who is always asking about "industry standards" and "trends" and statistics
for why you do certain things with interface design. So I use those words
when I talk to her about the interface. I might say, "well, of the hippest
web sites I've visited in the last 3 weeks, I've observed that designers are
doing it like this." Or I might get extreme and say "Jakob Nielsen, a leader
in web usability, says you should devote 90% of your page to content." (No,
I don't know what the actual number is right now!) (BTW, if you can't back
it up and it's not a big deal, back down sometimes. It helps.)

The owner of our company wanted to include in our product slicks screen
captures of software that was still in the initial design stage and for
which the only interface that existed was the paste-up I did in Visio! I
fought her on it every time she brought it up, saying that the interface was
NOT polished yet and that it would prematurely set expectations. Finally the
last time she said she wanted it, I just said "You don't buy my argument, do
you?" For some reason, that got through to her and she hasn't brought it up

As far as access to users, I tend to think that you're lucky to get any
access at all, so take what you're getting and be happy. I'm not sure what
you mean about "what tasks are appropriate." If they're telling you what
tasks the users will be doing, they probably have a good idea, though they
may not have the "task-oriented" perspective that focuses on the users'
overall goals and not just the product tasks. If you mean, the tasks you
need to complete to do your job, well, there it's a little trickier. Does
management want an outline so they can see if all the relevant information
is covered? That's not unreasonable. Are the developers trying to tell you,
perhaps in a roundabout way, that they have limited time for technical

There's always the communications approach, i.e., try communicating your
confusion about what the developers are doing. For a while my boss kept
coming to me with new document requests and he'd say, "I need a template for
this document." A template! Well that requires planning and information
gathering and blah, blah, blah. "I'd like it this afternoon." No frickin'
way! He'd go off frustrated that I kept telling him no and I was afraid he'd
think I was obstructive. Finally I told him we needed to talk and said, "I
don't want you to think I'm not wanting to do produce what you want. When
you tell me 'template,' that means a finished, abstracted document with ...
(etc.) " "Oh! No, that's not what I mean." All he wanted a rough outline.
Easy enough.

So, pick someone with whom you have a fairly good rapport, and say something
like, "you know, it sometimes seems to me during our meetings like you guys
are trying to tell me how to do my job when you say XXXX. Am I missing
something?" Or something like that. Sweetly project that you *know* how
silly it is to think that they'd do something as absurd as try to tell you
how to do your job, which is different from theirs, but that you're really
just wanting to clarify your impression.

Oh, and finally, if management is treating documentation as an afterthought,
then the developers likely will too. Not sure what to say about that. I've
always been fortunate to work where documentation was considered a key to
the product/project's success. I'm sure someone else has a good idea.

Okay, so there's some perspective with a little advice thrown in. Not
necessarily parallel to Lisa M's situation, but my take on why tech writers
do not have to be the downtrodden folks we sometimes seem. I'd love to
debate anything I've said, but I'm mostly offline for the next couple of
days, because we're suffering from a badly planned move at work and I'm in
the midst of a home renovation project in my non-working time. I'll be
interested to hear anyone else's response, just don't expect a quick answer!

Lisa Wright
Technical writer, office furniture assembler (this week!)
PeakEffects, Inc.

Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**WEST COAST LOCATIONS** San Jose (Mar 1-2), San Francisco (Apr 16-17) or 800-646-9989.

Sponsored by ForeFront, Inc., maker of ForeHelp Help authoring tools
for print, WinHelp, HTML Help, JavaHelp, and cross-platform InterHelp
See for more information and free evaluation downloads

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: HTML Help vs. WinHelp
Next by Author: Re: How to transition your work?
Previous by Thread: RE: Development/Documentation
Next by Thread: RE: Development/Documentation

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

Sponsored Ads