TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Effective Information Gathering? From:GhostWolf Davidson <ghstwolf -at- SLIP -dot- NET> Date:Wed, 3 Feb 1999 11:06:26 +0000
I've spent several hours searching many different writer archives
to resolve an issue I and my peers are facing.
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 be more
efficient for the writers and developers, and enable us to
release the documentation at the same time as the release.
We have a choice of two separate processes (described below).
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
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 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
* 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
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
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