Re: UNIX and Windows documentation

["Susan W. Gallagher" <susanwg -at- ix -dot- netcom -dot- com>]

Ted,

Your solution really depends on the type of application you're
documenting and the target audience's expected level of expertise.
I've done this sort of thing regularly for programmer tools and
the like; creating a document for end-users can be quite a bit
trickier. And, no, when management says they want only one set
of books, conditional text really won't do.

I've frequently used ID icons in the margin to separate Windows
stuff from Unix stuff. What you get is a sort-of "embedded table"
look. But it works best if there are small (maybe one step)
differences in a generally similar procedure.

Life becomes a lot easier if you generalize your procedures, too.
Saying "open the file in the text editor of your choice" works on
both platforms; but "open the file in Notepad/vi" get's awkward.

If command line stuff works on both platforms, use one prompt
consistently, changing only for other-platform-specific stuff.
Or use a variable like "<prompt>" for general instructions and
use platform specific prompts for ... <duh!>  ;-)

The thing is, if the instructions are written well and the
systems are really similar enough to justify a single book,
there shouldn't be "endless pages" that cover one platform
or another. The instructions for both platforms should mesh
seamlessly with occasional notes or single paragraphs of
differences.

And yes, installation instructions should be totally separate
for each platform. In the API world, I've often put out doc
sets with a single user and reference and up to <lessee...
Win, UNIX for HP, IBM, DEC Alpha, Solaris, real-time VxWorks,
hand-held Palm and CE...> eight or more separate installation
guides.

For major differences, use appendixes creatively; and if you're
delivering in html or pdf, use hyperlinks creatively to, again,
eliminate those "endless pages" of differences you spoke of.

Don't talk down to either audience. Assume that users on both
platforms have the same level of application expertise. Assume
maybe a little more system knowledge for UNIX users; but in
an office setting where business software is likely to be used,
this may not necessarily be the case. Your user may only know
how to log on and launch the application on UNIX but have a PC
running Windows at home.

HTH!
-Sue Gallagher
susanwg -at- ix -dot- netcom -dot- com



At 02:20 PM 4/2/02 -0500, Ted Rainey wrote: