Handling Conditional Text With Author-it

People often have a business requirement to create documents containing common information as well as information that is specific to the product being documented. Some products achieve this with a concept of "Conditional text" where information is included or excluded when certain criteria are met. We have chosen a different approach - a combination of:

1. Embedded Topics - allowing you to reuse chunks of text right down to paragraph level. You would not create a topic for each product specific sentence, but rather for the common information that you would then reuse in "Composite" topics which would contain your product specific information.
2. Composite Topics - these topics are made up of the specific information that relate to the product being documented, and common information can be added using embedded topics.
3. Variables - used for smaller chunks of text, such as product names, or product specific sentences.

So for example, in a situation where you want to reuse the "same" topic in the documentation of 2 different products A and B and:

• In the product A documentation, topic T1 contains 1 product A specific paragraph.
• In the product B documentation, topic T1 contains 2 product B specific sentences.

This product specific text appears in different places within the topic.

First, you would create two Books - one for Product A and one for Product B. Remember that you are simply reusing common topics, so you are still single sourcing. If you change the topic in one place, the change is made everywhere the Topic is used. You can also use sub-books for common chapters or sections - say for example, you had an Introduction or Installation section that was the same across your documentation set, you would create a Book for this section, then drag this Book into your main Product Book. The advantage of sub-books, is that when you update them - add, remove, promote and demote topics - the main (or master) Book is updated automatically.

Then, you would not create one occurrence of Topic (T1), but instead create two new topics (T1) and (T2) - one for each product. These two "composite" topics would contain the product specific information, and reuse embedded topics for the common information. This way you can also easily control the placement of the information in each topic. You would use Variables, either in the embedded or composite topics, for the product specific sentences.