Customer specific documentation with MadCap Flare

Are you documenting a product that consists of a bunch of modules? Do customers buy customized products with a unique set of modules? Would you like to deliver customer-specific documentation using MadCap Flare? Keep reading.

The idea is to use an existing product module database to generate the condition tags,  apply them to your content,  generate the customer specific target files, and then set it all up to run as an automated batch job in windows 🙂

The process

  1. Build a condition set based on all the modules of the product(s).
  2. Apply the conditions to your content 🙂
  3. Use customer data to create customer specific target files (if possible, export from your ERP system to Excel).
  4. Use the target files to generate unique output depending on what modules/options a customer has bought.

Client Specific Documentation

Here’s an example XLS file for you to play with 🙂

Building the condition set

The idea is to replicate the Flare condition tag set XML file (.flcts) using Excel. The structure you want to replicate looks like this:

cust_targets_condition_xml

To set up a condition set “generator” in Excel, set up a spreadsheet that looks like this:

cust_targets_excel_1

The Condition column combines the Product and Module names into a name for the condition.

The Flare XML column contains a formula that turns the condition into something we can put in the Flare condition tag set file (.flcts):

cust_targets_condition_xml_2

In addition to the conditions, we need to add the opening and closing XML tags: <CatapultConditionTagset> and </CatapultConditionTagset>:

cust_targets_condition_xml_3

Finally, we use formulas to combine all condition tags into a single cell that contains all the XML code we need for creating the Flare condition tag set file (.flcts). Have a look at the example XLS file to set how it’s set up. The final XML data looks like this, and is ready to save as a .flcts file in your Flare project:

cust_targets_condition_xml_4

When you’ve update the .flcts file in Flare, you now have a new set of conditions:

cust_targets_condition_xml_flare

Applying conditions to your content

Granted your content structure supports it, you can now apply conditions to the module-specific text and images etc 🙂 Have fun!

Creating customized targets

The next step is to create customized Flare target files (.fltar). Again, we rely on Excel formulas to generate the XML data we need. The .fltar structure for a (PDF) target looks like this:

cust_targets_target_XML_1

The Excel sheet looks like this (example XLS):

cust_targets_target_XML_2

The resulting XML looks like this:

cust_targets_target_XML_3

…and the resulting Flare target file looks like this:

cust_targets_target_XML_4

In the Excel file, we’ve only customized the condition tags, but you could easily set it up to customize the document properties (title, subject, etc) as well.

Generating Flare output files based on the customized targets

When all your target files have been set up, you can set up a .BAT file to run on a schedule to generate your targets on a daily basis to ensure that all content is up-to-date.

You can use Excel to create the batch file, by creating a formula that combine the madbuild.exe command line tool with the path to your project and target (e.g. madbuild -project C:PATHFlareProject.flprj -target MyPDF)

cust_targets_target_XML_5

Good luck, and have fun!
(I’m happy to help you create your your own setup – just ask :-))

2 Replies to “Customer specific documentation with MadCap Flare”

  1. Mike

    Is there a way to trigger conditional content on the fly?
    Like your example, I have a product that consists of a bunch of modules, and all of the modules are marked with conditions. However, I only want to output *one* target, and then programmatically tell the help which help topics to show/hide.

    I want to do this because we have too many combinations of modules to create separate targets for each one.

    • msander

      Hi Mike,

      You could use filetags in combination with a javascript that excludes/includes files based on the tag – but that’s a cumbersome solution.

      How many conditions do you have? I’ve written a little script that takes an existing target file, and a condition set – and then creates a target file for each valid combination of conditions. If that’s what you need – I’m happy to share 🙂

      Mattias

Leave a Reply

Your email address will not be published. Required fields are marked *