Re: single-sourcing cross-platform documentation

[Jean Weber <100241 -dot- 2123 -at- COMPUSERVE -dot- COM>]

Dan Roberts asked,
>> snip... snip
    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 prefer to have separate books for separate platforms, on the theory that
this is easier for users to follow and use (and should keep the books
smaller). Disadvantages (to you, not the users) are a bit more complexity
in maintaining the files, and possibly some printing costs related to
smaller print runs of more books. (If you use demand printing, the latter
should not be a factor.) One should, of course, always do what's best for
the users, but reality often intervenes.

You asked:
>> 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 have used Word6 to do this, using IF, THEN, INCLUDE, and some other stuff
(read on, but note that I'm writing this from memory, so the specific field
names I mention may not be exactly what Word calls them). It worked quite
well, but was fiddly at first to set up and get working correctly (probably
because I was learning how to do it as I went along, and made a lot of
mistakes that I didn't make the next time I worked on such a project).

If you choose to have separate platform-specific books, you definitely do
not want to maintain more than one copy of the common material. I'm
sure you know all the reasons why.

I see two different situations:
1) the common stuff is the majority, with small amounts of
platform-specific material.
2) the platform-specific stuff is the majority, with small amounts of
common material.

Obviously some chapters will be of type 1, others of type 2. How I handle
these differs.

For chapters of type 1, I keep one file for the common stuff, and use IF...
THEN fields to include or print platform-specific information when and
where needed. If the specific info is short, I keep it in the same file as
the common material, and use IF...THEN fields to make the right bits
print. If the specific info is long, I might put it in a separate file and
use
INCLUDE (again with IF to specify which file to include).

You have to do something else (SET or ASK, I think) to specify which
specific bits to use at print time. Sorry, I don't have the book with me
to look this up, and as I recall, it's not explained very well. (That's why

setting this up the first time was such a hassle.) You can probably
get detailed help from someone on the Word-PC list or the
TECHWR-L list if you need it.

For chapters of type 2, I keep separate chapter files for each platform and
use include to bring in the common stuff, which is kept in one place.
This can get a bit messy if the common stuff is scattered around in the
chapter, but works well if it's a block at the beginning, for example.

Remember that you can print to file as well as directly to the printer.  I
prefer to use this when doing proof copies, because gremlins can creep in
between one print run and the next.  Also it's essential if you are having
someone else print the final camera-ready copy; if you send them source,
they are unlikely to do whatever magic tricks are needed to get the correct

bits to print.

So that's the major caveat: it's more complicated for the writers to
maintain. However, as I said at the beginning, one should be making
decisions based on what's best for the users, not what's easiest for the
writers.

Another suggestion with all of this: annotate your files with hidden text,
to explain what's going on. This is vital if someone else is likely to have
to
maintain the files later, and very helpful even if you are doing it,
because you will not remember what you did later!

Hope this helps. Feel free to contact me to clarify or expand on any of
this.

Jean Weber
Technical Writing Consultant, Sydney, Australia