Content Reuse Wrap up: Putting it all together

(This is part five of a five-part series dealing with content reuse in the Help Authoring Tool (HAT) MadCap Flare version 3.1.)

Review

It’s time for a brief review: When we talk about content reuse, side effects we mean writing content once and then creating multiple outputs from that single source of content. Flare is a help authoring tool created by MadCap Software that allows you to single source your content in powerful ways. Flare includes tools for using variables, cost snippets, and conditional text to create a powerful source from which you can create multiple output targets.

Variables are small strings of text that you can replace for an entire project, and can even change for individual targets. You might include your product name and version as a variable. When this information changes, you can change the variable definition, and the project is instantly up-to-date. Snippets are like large variables. They are actually entire XML files that can include images, text, formatting, etc. You can use snippets for chunks of information that you re-use in multiple topics in your project. When you need to change that information, you change the snippet file, and all the topics that include that snippet are instantly updated. Conditions allow you to mark content (all the way from the character level up to the entire topic level) with conditions. When the project is built, you can include or exclude content marked with those conditions. For example, you can have one topic that includes some information or terms used in printed output, and other terms or information for use in online output.

Project Application

Today I thought I’d talk about a fictional project and show how with proper use of content reuse tools you can create several distinct outputs from a single source of text.

Suppose you are writing a user guide for a product we’ll call Widget. You give a basic version of Widget away for free, but you have a version of Widget called Widget Plus that requires a subscription. You have an OEM agreement with another company, and they bundle Widget Plus with their application, but they call it Super Widget. (For this example, we’ll assume the content in Super Widget is exactly the same as the content in Widget Plus; the branding, colors, and product name are the only differences. We’ll refer to these two versions as the advanced version of the application.)  All three versions have online (F1) help. Widget Plus and Super Widget also have printed guides (provided in PDF format).

In an old-school style help system without tools for content reuse, you would probably have to create several different projects; You’d need:

  • Online help system for Widget
  • Online help system for Widget Plus (with added functionality and Widget Plus name)
  • Online help system for Super Widget (with corporate branding of affiliated company)
  • Text-based project for Widget Plus
  • Text-based project for Super Widget (with corporate branding of affiliated company)

You recognize that these five outputs contain sections that are very similar (or even the exact same content in some cases, with just the name changed) but you end up maintaining five separate projects because you need five separate outputs.

Single sourcing with Flare (or another similar HAT) means you only need one project. You add all the content to the one project, and you just create five different output targets. Then you use the content reuse tools in your HAT to simplify the process.

In this project you would create two different TOCs and five different targets. You would want a TOC for the simplified Widget application, and a TOC for the advanced Widget Plus and Super Widget applications. You would create a separate target definition for each of the outputs I listed in the bulleted list above.

For this project you’d want to use a variable for the project name. Every time you reference the project’s name, you’d use the variable instead of Widget, Widget Plus, or Super Widget. In your topic you might see something like:

The Preferences screen allows you to customize the [variable:ProjectName] interface.Then, in each of the five target definitions, you’d update the variable definition. When each target is built, the proper project name is automatically inserted.

If you have chunks of content that you reuse in multiple topics, you can create snippets to allow you to reuse those content chunks across multiple topic files.

Then you would use conditions to customize your outputs.

For this project you might have the following conditions:

  • Basic
  • Advanced
  • PrintOnly
  • OnlineOnly

One way these conditions can be applied is to content within topics. The Preferences screen for the basic application may have fewer features than the Preferences screen for the advanced version of the application. You still only need one Preferences topic in your application. This topic includes all the features. The extra features can be marked at the paragraph level with the “Advanced” condition. The targets for Widget can be set to EXCLUDE the Advanced condition, and this advanced content is not included in the basic version’s help system.

You can also have text on the screen marked for online output only, with other content marked for printed output only. You might have the following text:

This [condition:print]guide[/condition][condition:online]help system[/condition] documents [variable:ProjectName].

The online help systems can include the “OnlineOnly” condition and exclude the “PrintOnly” condition. The printed guides can include the “printed” condition and exclude the “online condition.

In our fictional project this one sentence can be rendered five different ways, depending on the settings in the target file:

  1. This help system documents Widget. (“OnlineOnly” condition, “Widget” variable definition.)
  2. This help system documents Widget Plus. (“OnlineOnly” condition, “Widget Plus” variable definition.)
  3. This help system documents Super Widget. (“OnlineOnly” condition, “Super Widget” variable definition.)
  4. This guide documents Widget Plus. (“PrintOnly” condition, “Widget Plus” variable definition.)
  5. This guide documents Super Widget. (“PrintOnly” condition, “Super Widget” variable definition.)

You can also apply these conditions at the file level. You might have a feature that is only available in the advanced versions. You can apply a condition to this topic in the Content Explorer, and that topic will only be included in the advanced outputs. (Your basic TOC wouldn’t include the advanced functions obviously, but for a WebHelp target, the actual files will still be copied over, and would be available in a search. If you exclude the topic however, the files simply won’t be included at all in the output.)

To get the branding right for the OEM-ed Super Widget, you might create an additional style.css file, separate masterpages for printed output and online output, and a separate skin for the WebHelp output. In the target definition files for the Super Widget targets, you would change the style settings, masterpage settings, and skin settings to use these Super Widget-specific files.

Conclusion

I hope you can see the power in single sourcing your content. The content reuse tools in MadCap Flare are powerful. You can use a single project for an unlimited number of outputs. Your imagination is your limitation.

This concludes my five-day series on content reuse in MadCap Flare. Feel free to share your comments with me, either as part of the posts in this series, or by contacting me via my contact form. You can also look for me in the MadCap user forums where I go by the name Doc-Guy.

Good luck single sourcing your content. It is worth the effort.

2 Responses to Content Reuse Wrap up: Putting it all together

  1. Steve Salter December 5, 2007 at 2:58 pm #

    Great blog, Paul.

    I might add another facet to content re-use: If you have 2 Flare projects open you can drag and drop content from one project to the other.

    Normally Flare uses the Windows “rules” when working with files, but in this case it will change the drag and drop to be a copy (rather than move), even if the project is on the same drive.

    If you maintain the topics you share in one folder, and the images in another (and only have the shared content in these folders) you can easily reuse content.

    Cheers!

  2. Tom Johnson January 9, 2008 at 8:48 am #

    Nice write-up, Paul. You’ve got a lot of detail there. One question I have is where Blaze fits in. If Flare is a single sourcing tool with PDF output, why do we need a Frame-like tool? Couldn’t we just write it in Flare and output to the same output Blaze provides?

Leave a Reply