Strategy for Handling Conditional Text

[David Spreadbury]

I have been following this thread with interest. I, personally believe that
conditional text would solve your problem, but, I was recently involved in
documenting a software application that was targeted for Windows and Unix.
The client did not want to use conditional text. So, we were left with
creating separate sections for Unix and Windows, only where there were
functional differences. This primarily occurred with installation and
maintenance, i.e., backup, restore, type procedures. Our solution was to
document the platform-specific procedures consistently in the same order.
The installation section would document the Unix-specific procedures
followed by the Windows procedures. The same was true whenever this
situation arose. The headings were, usually, identical except to refer to
the platform; "Installing on Unix" followed by "Installing on Windows". I
worked out very nice.

The big advantage of doing it this way is production of one document instead
of two, which made follow-on maintenance was much easier; only one book to
muck with.

Just a second opinion.


David Spreadbury
Sr. Technical Writer


-----Original Message-----
From: framers-bounces at lists.frameusers.com
[mailto:framers-bounces at lists.frameusers.com] On Behalf Of Bill Swallow
Sent: Monday, April 12, 2010 4:27 PM
To: Bernard Aschwanden (Publishing Smarter)
Cc: framers at lists.frameusers.com
Subject: Re: Strategy for Handling Conditional Text

> That means think a lot about what you write. With one client we took the
approach of a Mac and a PC version of manuals, but we had,
> say, 10 chapters that had the same info. We avoided product names. We
asked the developers to match the product and dialogs. Then we
> wrote generic. Instead of "on the PC, click FOO to open the Windows
Explore" and "on the Mac, click YADDA to open the Finder" or
> whatever, we wrote "Open your file browser", and similar things. The
assumption was that the user would either know how to do it,
> look it up in the chapter on Mac Specific Functions and Tips, or ask a
person "how do I do *this*".

Generally I agree, but I think in this specific case the application
that Joe is documenting really varies between Linux and Windows. At
least, that's what I gathered from: "Originally, I was told that these
differences would eventually go away and that the user experience
would be identical on both operating systems. This hasn't happened.
The differences have grown."

In this case, I think it's best to *advocate* for the generic approach
but until it's achieved on the application side conditions are likely
the best solution. As the applications become more similar, the
conditioned document can be generalized and conditions removed for
those general portions.

-- 
Bill Swallow