single-sourcing cross-platform documentation [LONG]

[dan roberts <dan_roberts -at- IBI -dot- COM>]

     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!!!