Re: a question about writing instructions

Subject: Re: a question about writing instructions
From: GeneK <gene -at- genek -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 06 Feb 2003 12:47:17 -0800


Based on your post, I am assuming you're a direct-hire and not a
contractor. I would add my agreement to those telling you not to
make a lot of noise about changing the company's formats as a
new hire (unless other writers happened to tell you during your
interviews that the consensus among the writers was already that
the format needed changing). I just spent two years managing
a publications group that was constantly at odds internally over their
style guide, and a huge percentage of the noise was generated by
two newly-hired writers (who came onboard just before me) who
were trying to drive format changes before they'd even finished
their first projects. They were immediately branded as "troublemakers
and complainers" by the rest of the writing staff, and were never able
to overcome that first impression. OTOH, as a new hire your manager
*should* be expecting you to ask questions about how to best do your
job (the new hire who asks no questions always scares the hell out of
me), and this is a good opportunity to get informed on how the style
got to be the way it is, how entrenched it is, how it goes over with
document users, etc., without branding yourself as a "complainer."
If you can ask these questions in a tone that projects curiousity
and a desire to learn rather than criticism, you may discover that
everybody already hates the style and is looking for a fresh point
of view on how to update it.

And to answer your second question, IMO the current style is a
usability disaster that sounds to me as if someone copied it direct
from a software writer's notebook.

Gene Kim-Eng
Technical Publications Manager
Half Moon Bay, CA

At 06:05 AM 2/6/2003 -0800, Becca Price wrote:

I recently started in a new position where the house style is to
not write out instructions as steps, but rather in narrative
form. That is, rather than having step 1, step 2, etc, an
instruction might read (under a header like "Using the XYZ
Screen"): "To add an item to the data base, enter the specific
information and press Add. To locate an item already in the
database, enter any information you may have, and press Search.
If more than one item matches your criteria, you will see..."
You get the idea.

This is a made-up situation; no comments about the design of the
mythical page or database or use thereof, please! My question is
strictly about format.


Buy or upgrade to RoboHelp X3 today and receive the WebHelp
Merge Module for FREE ($299 value). RoboHelp X3's all-new
features include conditional text, completely re-engineered
printed documentation output, Context-sensitive Help Toolkit,
single-source layouts, and more!
Order online today 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.

a question about writing instructions: From: Becca Price

Previous by Author: Re: want ads/job titles
Next by Author: RE: credit check for interviews
Previous by Thread: RE: a question about writing instructions
Next by Thread: Re: a question about writing instructions

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

Sponsored Ads

Sponsored Ads