Many of our customers come to us because they see the value in single-sourcing their documentation.  Of couse it is simple and cost-effective to maintain a single document that provides multiple outputs – much simpler than trying to juggle multiple individual files. 

When designing the single-source document, one of the first considerations has to be how you will manage the content.  To this end, there are two primary methods:  Conditional Formatting and Attribute Filtering.  What is the difference between the two?  What circumstances would make one more appropriate than the other?  These are some of the questions that we are frequently asked.  To address these questions, let’s take a look at each of these methods.  For these examples, I will be using Adobe^® FrameMaker^® as my editor.

Conditional Formatting

Conditional tags can be applied to individual characters, words, sentences, or whole paragraphs.  You can then display or hide the tagged text within the document with a few clicks of the mouse.

Before you begin to write your document, make a list of the conditions that you may need to set.    For the purposes of this example, I have identified two conditions: Condition A, and Condition B.  Once these conditions are identified, you can create condition tags.  Some editors allows you to designate text colors that will be displayed once a tag is applied.  These colors are called Conditional Indicators.  You can turn these indicators off globally before you print or export your document.   I chose to use Green for Condition A and Red for Condition B.

As you develop your document, mark content that you would like to manipulate with a conditional tag.  First, select the text, and then apply the predefined conditional tag. 

Once your document is complete, you can manipulate it by showing or hiding certain conditions.  In the example below, I have hidden both Condition A and Condition B. 

 The next example shows Condition A and hides Condition B.

This method of manipulating a single sourced document makes it easy to manage multiple input combinations; however, it does not lend itself well to multiple output levels.

Attribute Filtering

Attribute Filtering provides more options than conditional formatting; however, it is applied at a higher level.  Where conditional text could be applied to a single character, word, or sentence within a paragraph, attributes are applied to the paragraph itself.  If you have to change just one character in a paragraph in order to achieve the desired output, you will need to duplicate the paragraph, make the change, and apply different attributes to each.

To apply attributes, you must be working in a structured document.  As you develop your content, set the appropriate attributes and their values.  For example, you could have an attribute of “Condition” with possible values of “1“and “2.”  Additionally, you could have an attribute of “Level” with possible values of “A “and “B.

1. Attribute = Condition
   1. Value = 1
   2. Value = 2
2. Attribute = Level
   1. Value = A
   2. Value = B

Once your attributes are assigned, you can develop filter expressions.  Filter expressions are Boolean expressions that dictate what content is displayed or hidden.  Some possible filters for the above attributes and values are:

1. Common Text Only:

NOT (Condition=”1” OR Condition=”2”) AND NOT (Level=”A” OR Level=”B”)

2. Condition 1 + Level B

NOT (Condition=”2”) AND NOT (Level=”A”)

3.  Condition 2 + Level A

NOT (Condition=”1”) AND NOT (Level=”B”)

4. Level B only

NOT (Condition=”1” OR Condition=”2”) AND NOT (Level=”A”)

As you can see, attribute filtering is a powerful means of controlling various outputs; however, it works best when there is a singular input.

To further illustrate, let’s take a look at two hypothetical clients.

Hypothetical Client A

Client A produces one basic type of heavy industrial equipment; however the machine is customized for each customer.  There are 82 possible features and options, giving them an almost limitless potential for customization.  It is impractical to pre-write individual user manuals and product guides for every potential configuration.  It is ineffecient to create a draft-to-print custom manual and guide for each possibility.

The output will always be either a pdf or a printed document, and will always be delivered to a consistent audience level.

Using conditional text is the correct answer in this case.  The output is always the same level (ie. there is only one audience), it is the input that changes.  Manipulating the document by setting conditions allows you to precisely control the features and options that are included.

Hypothetical Client B

Client B produces a few different industrial machines.  Each machine requires three levels of publications: a Product Operation  Guide, a Preventative Maintenance System, and an Installation Manual.  Each of these manuals will focus on different aspects of the same machine.  Some of the content in each will be common; however, the steps that are required for various processes will vary greatly from one user level to another.

In this instance, the input is constant while the output changes.  Attribute filtering would be appropriate for Client B.  Manipulating the document by filtering attributes allows tight control over the documents that are produced, ensuring that the correct information gets to the correct audience level.

Choose Wisely

Each of these methods requires a different approach to writing your document.  Before you begin to develop your content, ensure that you have selected the best method of managing content.  Choosing correctly makes it easy to produce the desired results.