[no subject]

From: "Cyrus, Valerie (IPCG - NJ)" <CyrusVa -at- EXCHANGE -dot- ML -dot- COM>
Date: Wed, 3 Feb 1999 14:23:28 -0500

I think the first approach is best. However, I think the writer should also
do the information gathering because it opens up the channels of
communication with programmers and developers. The project lead person
should probably act more like a project manager and coordinate the
scheduling of different products so that you guys can get things out on
time. The project lead should be present at development planning meetings
and let the development team know what resources are available at any given
time. This way perhaps some lead time can be built into the development
process for documentation and you can deliver it in a timely manner.
Valerie Stout Cyrus
IWS Documentation

-----Original Message-----
From: GhostWolf Davidson [SMTP:ghstwolf -at- SLIP -dot- NET]
Sent: Wednesday, February 03, 1999 6:02 AM

Hi, all;

I've spent several hours searching many different writer archives
to resolve an issue I and my peers are facing.

Some background:

We are a group of four writers responsible for documenting a
very large RDBMS "seed to shelf" product line comprised of five
separate software packages; two of which are written in-house,
and the other three by separate companies, running on a very
wide array of platforms from UNIX to WinNT.

The documentation environment is WinNT, using FrameMaker 5.5.3,
RoboHelp, and various graphics packages.

The documentation is comprised of 82 (yes, you read that right);
approximately 60 of the manuals are provided by the corporations
of the partnership, and we are responsible for the remaining
manuals, which cover installation, configuration, integration,
implementation, customization, APIs, and more. This does not
include the online help nor the support web sites for which we
are also responsible.

Naturally, we are heavily back-logged, and documentation for each
release has typically lagged behind the release by one or more

We are attempting to implement a process that would enable us to
release the documentation at the same time; and are having two
choose between two different approaches.

Heh - one obvious answer is hire more writers; but the powers that
be have nixed that solution.

Currently, each of us writers is responsible for specific manuals;
and several of those manuals address all of the components and the
interrelationships between those components, such as the
configuration, implementation, integration, and technical reference


What I need is feedback on the pros and cons of the following two

Approach 1 (Our current approach):

* Each writer is responsible for specific manuals

The advantage is the writer becomes aware of the
between each component, and thus would see how a change to
component would impact another and be able to write

This is very critical, imo, because if one item is missed
the installation, integration, and implementation process,
end user has to literally wipe the system and start over.

A second advantage is that the overall style (corporate style
guide notwithstanding) and presentation is consistent
each manual.

* The project lead for each of the product components gathers
information from his/her developers, and provides that
to the appropriate writer.

We've already developed templates for the input and feedback,
some developers and leads like the templates; others resist.

One advantage is the developers have a single "interface"
that understands their - and documentation - needs, freeing
from having to set aside time for each writer.

This also frees the writers from having to set aside time -
coordinate time - with each developer.

Another advantage is the project lead is very aware of the
documentation needs, and also has a "big picture" view
of each of the subcomponents that, in our opinion, is very
valuable to the documentation team.

Approach 2 (Proposed by higher management):

* Each writer is assigned specific components of the entire
line, and documents only that component *in each of the

The advantage is the writer - over time - becomes a subject
expert for those components.

One disadvantage is having to coordinate updates in each of
manuals that addresses more than one component.

A second disadvantage is loosing the synergy of having "the
picture" for a particular manual - our concern is that a
change to
one component that does impact another will be missed.

* Each writer is responsible for obtaining the information from

I think this is the traditional approach in most
but am not certain.

* Each writer is responsible for coordinating and sharing
with the other writers.

This may offset the loss of having "the big picture" view for
specific manual.

The disadvantages that I and my peers see with this approach

* an increase in the amount of time obtaining needed data from
developers with a subsequent decrease in the time we have to
write and they have to develop and refine code

* the writers would spend additional time coordinating changes
the same document, again decreasing time available for

I and my peers see the second option as increasing the amount of
we spend in obtaining and coordinating information, and decreasing
amount of time we have to produce documentation.

However, we also realize we may be mistaken, and thus this request

Per the FAQ, I will summarize the feedback.

Thanks in advance;


From ??? -at- ??? Sun Jan 00 00:00:00 0000=
Send commands to listserv -at- listserv -dot- okstate -dot- edu (e.g., SIGNOFF

From ??? -at- ??? Sun Jan 00 00:00:00 0000=

Previous by Author: Re: Non-standard but industry-standard word lists
Next by Author: Re: What documentation tool?
Previous by Thread: DataBuilder
Next by Thread: Influent Technology Group Online Seminars

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

Sponsored Ads

Sponsored Ads