single-sourcing cross-platform documentation [LONG]

Subject: single-sourcing cross-platform documentation [LONG]
From: dan roberts <dan_roberts -at- IBI -dot- COM>
Date: Tue, 10 Dec 1996 10:11:25 EDT

The environment:
I help doc a cross-platform, client/server product providing
heterogeneous DB access. In other words, we enable end user
applications on a number of platforms to access multiple relational
and nonrelational DBs on a number of other platforms. Our product is
based on 'core' functionality that is implemented according to
platform needs (for example, our HOMEPATH is a ddname in MVS pointing
to a pds, an environment variable in an INI file in WinNT pointing to
a subdirectory, an environment variable in UNIX - you get the idea).

Currently, each platform has all related information in 1 book. We
discuss 'core' functionality in general terms in a number of files
that we pull into each book, as the first several chapters in the doc.
Then, following chapters relate the general information to
platform-dependant details.

The problem:
Our doc group is attempting to break apart the books into a number of
books, aimed at specific audiences, for specific tasks (ie, an
overview to the product <marketing-ish>, install/configs for the
various platforms, console operations guides for the various
platforms, a common diagnostic to cover cross platform errors and
debugging.

The one doc we are stumped on is an Admin Guide. Some of us
(developers and writers) see the Administration functions as a set of
platform-dependant functions; others see administration functions as a
set of standard tasks or capabilities, with the platform-details being
relatively minor issues. In essence, we've got a conflict between a
bottom-up approach (an Admin Guide for each platform) and a top-down
approach (a common Admin Guide, with platform-details scattered
throughout).

The questions:
For those of you that document similar types of cross-platform
products, which approach do you take to documenting 'core'
functionality? what advantages are there to your approach?
* If you take a top-down approach, what do you do with the
platform-dependant details? What do you do when a particular function
is supported only on 1 platform, or is not supported by a specific
platform?
* If you take a bottom-up approach, how do you ensure that common
functions are consistently documented in all applicable locations?

Has anyone used MS Word 6 to single source documentation like this?
Perhaps the includefile feature or the includetext feature? Any luck?
Any caveats?

I welcome comments and information from everyone. I'd especially be
interested in comments from DB writers (such as Oracle, Sybase,
Informix, or similar), since we target similar audiences. Replies to
the list or to me directly are both welcome.

Thanks for any information anyone can provide!!!


Previous by Author: Re: Readability of extended list items?
Next by Author: Ebonics: getting Off Topic?
Previous by Thread: Problems printing Acrobat files
Next by Thread: Query: User Demographic Info Sources


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


Sponsored Ads