Re: Fighting a losing battle

Subject: Re: Fighting a losing battle
From: Andrew Plato <intrepid_es -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 25 Sep 2001 07:32:07 -0700 (PDT)

"Hanlie Pretorius" wrote

> For the past 9 months I've been documenting a Java system in
development. I
> started very enthusiastically, suggesting improvements to screen
> pointing out (to the business analyst) inconsistencies in screen
> spelling errors (!) and so forth just to have my ideas squashed by the
> don't have enough developers to spend on trivial things like that"
> Although it was phrased more diplomatically.
> Eventually I stopped spending time on pointing out errors I found but
> time a new screen comes out, I just want to scream with frustration at
> bad design. The usability of these screens is *terrible*.

If you were not hired to do usability, don't assume it is your job. This
is an area that routinely gets tech writers into trouble. They just assume
they are usability experts and take on a job that may not be assigned to

I am going to guess, and granted I don't know all the particulars about
your situation, that your "enthusiasm" in the beginning was taken as
"uncalled for" by the engineering staff. If you leap into a project and
start making corrections and changes on day one, you can step on egos and
enrage people. You wouldn't like it if some guy, who you did not know,
started ragging on your documentation.

Your suggestions may have been good, but your timing may have been off.
You have to earn the right to criticize people's work. You cannot just
walk into a project and assume you are the sole "advocate for the user."
If you were hired to write documents - write the documents. Don't take on
jobs that were not assigned to you. Sometimes the best way to point out
errors is merely to document them as a matter of fact.

Also, remember that usability is in the eye of the beholder. Usability is
not a science or an equation. It is a matter of personal preference,
taste, mixed with trends and fads. Your perception of usability may not
match the engineers.

As much as this enrages many writers, I personally think usability (along
with readability) is another one of those subjective ideas that writers
try to make objective. They don't want to fess up to the fact that these
are overwhelmingly an issue of personal preference and trend - not some
hard and fast science.

> My question is this: how do you think I should deal with this? I've
> the positive criticism approach, the laissez-faire approach of accepting
> as part of the imperfections in the universe but none of these prevent
> from looking at my bag and considering the distance to the door every
> one of these hideous monsters enter the world.

You may have already tainted the environment. So you need to start over.
Work on getting your job done FIRST. Write the documentation you were
hired to write. Assume that what is given to you is golden and just doc
it that way. Wait until you have proven that you can do the job you were
hired to do FIRST. Once you have done that, then try to work into helping
with the screens.

Try and get a feel for what your company is trying to accomplish. Don't
just jump in and say "these screens are horrible". Look at the broader
picture and ask "what are we doing here?" and "does this get the job
done?" If it meets those two requirements, then everything else is icing
on the cake. That icing may be important, but it might not be possible in
the first revision.

Back off and do the job you were hired to do. Be a tech writer first and a
usability expert second. Once you have earned the respect of the
engineers for great docs, they will be more receptive to your suggestions.

Andrew Plato

Do You Yahoo!?
Get email alerts & NEW webcam video instant messaging with Yahoo! Messenger.


Planning to attend IPCC 01, October 24-27 in Santa Fe? Sign up by
October 3 and get a substantial discount! Program information,
online registration, and more on

+++ Miramo -- Database/XML publishing automation. See us at +++
+++ Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion +++
+++ More info: +++

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: Contracting where you used to work
Next by Author: Re: Developing Charter for Documentation Dept.
Previous by Thread: Re: Fighting a losing battle
Next by Thread: RE: Fighting a losing battle

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

Sponsored Ads