Best Practices for Conditional Build Expressions

[Jeremy H. Griffith]

On Sun, 9 May 2010 17:56:40 -0500, Joseph Lorenzini <panopticon23 at gmail.com> 
wrote:

>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.

Yes.  I'd consider that a best practice.  It minimizes complexity.
The need to create two conditional xrefs is one that is sure to bite
you sometime, and you avoid that trap nicely.

>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?

No, it's a very good idea, IMHO.

>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.

Another very good idea, especially if you ever intend to
translate.  You could go down to sentences (but no lower),
and still be OK.  But your method is definitely easier to
maintain correctly, without winding up with missing or 
extra spaces between sentences, for example.  Go for it!  ;-)

-- Jeremy H. Griffith, at Omni Systems Inc.
  <jeremy at omsys.com>  http://www.omsys.com/