Re: Multi-platform Docs

[Beverly Parks <bparks -at- HUACHUCA-EMH1 -dot- ARMY -dot- MIL>]

Catherine Rivi asks about documentation written
for multi-platform products:

> I am looking for examples of documentation (good or bad)
> written for a multi-platform product. I am interested in whether
> anyone has covered platform differences in the same document and
> done it effectively.  Any pointers to documents or success/horror
> stories are appreciated!

=====================
I was a programmer on a communications system that ran under DOS
but for security reasons could be certified only on specific
platforms. Installation instructions were contained in an
appendix to the users manual. Simple platform-specific changes
to the config.sys and autoexec.bat files were detailed in the
manual with statements such as "If your system is on the [name]
platform, you need to modify your CONFIG.SYS file to contain the
following lines:
   ...
"If your system is on the [other name] platform, you need to
modify your CONFIG.SYS and AUTOEXEC.BAT files.

"The CONFIG.SYS file must contain the following:
  ...
"The AUTOEXEC.BAT file must contain the following:
  ..."

Hardware configuration differences among the various platforms
were much more complex. Rather than detail all this information
in the hard copy manual, we provided a "soft doc" file with the
software; we called it the TECHINFO program. In the users manual
we described what the TECHINFO program was, how to start it, and
how to use it. The TECHINFO program itself was a text file
consisting of several chapters for the different platforms and
subchapters for the specific hardware components. It was not a
true hypertext file, but users could jump to specific chapters
and sections by entering a chapter or section number from the
table of contents. Users could choose to print the whole thing,
any chapter or range of chapters, or any section or range of
sections.

Overall, this hard/soft document combination was very
successful. Our users *did* read/use the TECHINFO file. There were
some, of course, that didn't read it until after calling customer
support, but I think that's a common occurrence even with the
hard copy manuals.

I hope this information is useful.

    =*=  Beverly Parks =*= bparks -at- huachuca-emh1 -dot- army -dot- mil  =*=
   =*=  "Unless otherwise stated, all comments are my own. =*=
    =*=   I am not representing my employer in any way."  =*=