Content Reuse In-Depth: Snippets

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

Yesterday we talked about variables. Today I want to expand on that discussion and talk about snippets. Think of snippets as long variables that can contain formatting and text.

If you’ve used variables for a while, view you’ve probably found yourself wishing you could include more than just short text in the variable definition. Suppose there is a procedure that you include in multiple locations in your documentation — the first three steps are the same in all these procedures. You’d like to create a bulleted list with these three steps that you can update in one location if that changes. You can’t do this in a variable.

Enter snippets.

Snippets are basically topics that can be imported into other topics. They are chunks of XML text that can be used multiple times anywhere in your project.

In the example above, you can create a snippet with the ordered list with the first three steps. You import that snippet into your content wherever it is needed. If something in those three steps changes, you can update the snippet file, and all your topics are automatically updated.

Some content authors use snippets to include a copyright footer at the end of every topic (Flare includes a better way to do this, using master pages, but I do know that some people still chose to include them in every topic.)

You can create a snippet file and name it “copyright”. Then you can import that snippet at the end of your topics. When the year changes and you need to change your copyright text, you can just edit the snippet and all the instances are updated.

So, how do you create and use snippets in Flare? It’s actually quite easy.

If you are creating a snippet from scratch, you can just go to the Project menu, and select “Add Snippet…”

In the dialog box, you give the snippet a name, and click Add. You’ll be prompted to confirm adding the file to the project; click OK. The snippet is added.

The new snippet is displayed. It works just like a Flare Topic. You can add any content to the snippet that you can add to a Flare topic. When you created your snippet, it was linked to the default CSS style sheet in the project, and you can use those styles as you create your snippet. If, however, the topic you insert the snippet into uses a different style sheet, the snippet will use the styles inherited from that topic (unless you make your style changes in line). This is actually handy; you can insert the snippet without worrying what the style will look like, because it will match the topic in which it is embedded.

Now that you’ve created your snippet, you’ll want to insert it into a topic. Snippets live in the Content Explorer in the Resources folder in a folder called (oddly enough) Snippets. This folder doesn’t exist in a project until a snippet has been added to the project.

Open a topic, and insert your cursor where you want the snippet inserted. On the Insert menu, choose Snippet. In the dialog box, locate the snippet and click OK. The snippet is added to your topic.

This is the best method to create a multi-paragraph snippet, or one that includes images.

You can’t edit the snippet in a topic. This prevents you from accidentally editing a snippet that might affect other topics. You can right click on the content of a snippet and select “Open Link…” for quick access to editing a snippet.

If you want to convert an existing element into a snippet, you can click on the element’s block in the XML editor, and select “Create snippet…”. The default behavior will allow you to name the snippet, and the source content will be replaced by the new snippet (which you can now reuse in another topic). The down side to this is that I haven’t figured out a way using this method to create snippets that contain more than one element. I can create a snippet that contains a <p> element, or a <ul> element, but I can’t figure out how to get two adjacent <p> elements into a single snippet using this method.

Snippets are fabulous for two reasons. First, because they are single sourced content, you only have to make changes in one location, and all the topics that use that snippet are automatically updated. Second, if you are localizing your help system, generally you pay for every word translated. By reusing the same procedures over and over, you only translate the snippet once, and you get to reuse it as many times as you need, saving you time and money.

Along with variables, snippets provide you with the flexibility to single source and reuse content in powerful yet simple ways.

A final word about snippets: I think you’re going to find in the neat future that Snippets are even easier to use when MadCap releases the Analyzer product. I’ve linked to the product page, but the part that is interesting in this discussion is the “snippets suggestion” feature. According to their marketing material, Analyzer will search through your project for places where you use the same phrase or segment of text (and images?). Analyzer will show you these chunks of text that you reuse frequently, and let you decide if you want to convert them into snippets, which Analyzer can do with just a couple of mouse clicks. It sounds like a powerful feature. I’ll review it here after Analyzer is released.

Tomorrow we’re going to continue the series on content reuse as we discuss Flare conditions. Then the next day we’ll wrap it up with some concrete examples of putting it all together. Stay tuned!

Day 4: Conditions

One Response to Content Reuse In-Depth: Snippets

  1. Austin Wright March 25, 2008 at 1:10 pm #

    Paul,

    In response to your comment “I can’t figure out how to get two adjacent elements into a single snippet using this method”, there’s an easy answer!

    Just highlight the content of all the combined elements in the XML Editor using the mouse, then select “Create Snippet” from the application’s Format menu. Voila! The Create Snippet dialogue will appear and allow you to create a snippet containing multiple elements.

    Regards,
    Austin Wright

Leave a Reply