Best Practices for Conditional Build Expressions

[Joseph Lorenzini]

Hi all,

Part of the product I document has a web interface for performing
administrative functions. Our product can be installed on Windows and Linux.
The product's UI and functionality changes based on what OS the product is
installed on. Because the product's functionality is identical in many
respects regardless of the OS, I am using conditional build expresions
(Linux and Windows) to avoid creating two documents. Originally, I was going
to apply them section by section including the section headings, but then I
realized this would be problematic for cross referencing. In many cases, the
labels remain the same, its the actual explanation or screen shots that
vary. When I cross reference a topic, I don't want to create two cross refs
- one for windows and one for linux -- since that would defeat the purpose
of conditionalizing the content. I want one cross ref to correspond to one
topic -- not two cross refs where each one corresponds to the target OS's
topic.

For example, there is a tab in the Web interface called "Components". This
tab is labeled the same in both Windows and Linux. There is a components tab
section in the user guide. When I cross ref the topic, I want to just refer
to the components section instead of "the components tab for linux" and the
"components tab for windows". Consequently, here's the idea I came up. I
plan to conditionalize *just *the paragraphs within the topics but NOT
conditionalize the topic headings. This means that the linux content and the
windows content will be in the same topic together. Does anyone think this
is a bad idea? Will this cause me more problems then its worth in the end?

The one issue I can think of is that I increase the risk of accidentally
mixing linux and windows content since there will be no topic headings
separating the content. However, I think that's fairly minimal as long as I
conditionalize the each paragraph correctly to begin with. I use very
distinct colors for each condion (linux is green, windows is purple). I will
also ONLY conditionalize paragraphs -- I will not conditionalize words or
sentences.

Sincerely,
Joseph Lorenzini