Documentation problem

Subject: Documentation problem
From: smithelizabeth -at- hotmail -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 13 Sep 2002 09:02:25 -0600

I have an ethical dilemma.

I was hired on about a year ago to create online help and also to update
Administrator guides. A former employee outlined exactly what he wanted
me to create: outline certain, specific tasks performed by the database
management group. It is not meant to encompass all aspects of
Administration. There are a lot of screen shots, step by step information.

There is another manual, the Administrator's Guide. This is the last
updated version. This contains relevant aspects of all Administration.
This is reference-based. It is not meant only for the database admins, but
others, too.

Ever since I began this project, it's been awful. (I created other
documentation for others within this group, and it all worked well). Our
change manager is creating barriers to effective documentation. She wants
not to update the original, comprehensive manual, since "the admin manual
is not a high priority for the team. None of the new admins even have the
old manual, so they are not using it at all." However, I see people
consulting the 1994 version all the time, with notes and sticky notes all
over for what's changed.

She suggests the following:

1. "Create the new Adobe structure and layout of the admin manual. This
would allow you to setup and get ready to begin the updates. That would
be the first one we schedule and we would tackle that one fairly soon."

2. "As we work on CRs that have impact to the admin manual, you can
include hours to update the manual when you are working on the CR. The
primary issue here is to make sure we tackle the highest priorities first.

This is all well and good, but what I created doesn't match the old
manual. The change manager doesn't understand that new information added
to just a small part of the old manual will just be that: an old manual
that no one will use, since most of the info is not true anymore.

My style of writing manuals, is to talk with all relevant people (admin
manager, admin themselves, SME's) and to come up with a coherent, working
document. I am always told to "add this to the manual," but where? how?
There is no place at the moment. I am not encouraged to work with the
admins. I have always worked well with a team before, figuring out their
needs and creating docs to help them. I find roadblocks every step of the

She's also having a requirements person write requirements for an addition
to the "manual!" Isn't requirements usually written for software, or do
people write formal requirements for info added to a manual?

Sorry to be venting. Hope this message is understandable. I'm at the end
of my rope. Any advice would be helpful.

Absolutely FREE! FrameMaker/Win 6 & 7 Express Customization (v3):
Quick-access buttons & keys to common functions, char tag/font drop-down
lists, charset browser, QRef guides & much more:

Experience RoboHelp X3! This new RoboHelp release combines single sourcing,
print-quality documentation, conditional text and much more, into the most
monumental release of RoboHelp ever!

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: @!#$%& plain text is a pain in the ASCII
Next by Author: Footer disappeared in Word 2000
Previous by Thread: RE: Orwellian Job Title
Next by Thread: Re: Documentation problem

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

Sponsored Ads