[no subject]

From: GhostWolf Davidson <ghstwolf -at- SLIP -dot- NET>
Date: Wed, 3 Feb 1999 11:01:44 +0000

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
months.

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 installation,
configuration, implementation, integration, and technical reference
manuals.

OK.

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

Approach 1 (Our current approach):

* Each writer is responsible for specific manuals

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

This is very critical, imo, because if one item is missed during
the installation, integration, and implementation process, the
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 throughout
each manual.

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

We've already developed templates for the input and feedback, and
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 them
from having to set aside time for each writer.

This also frees the writers from having to set aside time - and
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 product
line, and documents only that component *in each of the manuals*.

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

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

A second disadvantage is loosing the synergy of having "the big
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 the
developers.

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

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

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

The disadvantages that I and my peers see with this approach are:

* 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 to
the same document, again decreasing time available for documentation.

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

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

Per the FAQ, I will summarize the feedback.

Thanks in advance;

GhostWolf

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




Previous by Author: Re: Capitalization from GUI
Next by Author: Effective Information Gathering?
Previous by Thread: Re: Non-standard but industry-standard word lists
Next by Thread: Effective Information Gathering?


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


Sponsored Ads