Technically Speaking

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

Now that we’ve covered variables and snippets in depth, I want to talk about another tool that Flare includes that makes content reuse possible: conditions.

Conditions are settings that are applied to content. When a target is built, that content will either be included in the target, or excluded in the target, based on the conditions. For example, you can have some content that only appears in online versions of your help, and different content that appears only in print version of your help.

You may want to include a simple procedure in your online help, but for the printed guide, include additional paragraphs of information. You use the same topic; you just mark the additional content with a print-only condition, and exclude the print-only condition in your online output.

Conditions can be applied at the character level, paragraph level, or topic level. That means that you can choose to include/exclude a character, a word, a sentence, an entire paragraph, a series of paragraphs, or an entire topic.

In my Flare projects, I typically use four conditions:

• printOnly
• onlineOnly
• internalOnly
• doNotDistribute

I’ve already addressed the print/online only conditions. My internalOnly condition is associated with internal versions of our target files. In our release notes, for example, I add the bug number after known issues, or after resolved issues so we can track them from release to release. We don’t want this information published in our customer-facing version, but I do want it in the guides I release to our support staff (so if they have questions about a particular issue’s progress, they can open the bug tracking system to the specific issue).

I apply my doNotDistribute condition to text that I only want to see in the Flare editor. This content isn’t included in any Flare output; it just exists in the source files. This allows me to leave notes for myself in individual topics that I can easily see when I am looking at a topic. Because the condition is excluded from all my outputs, I never have to worry that these pubs-staff-only notes will be included in an output.

If you produce multiple versions of your content, you can use conditions to mark some content as basic and other content as advanced. You can then exclude advanced content from the basic guide, and include it in the advanced version of the guide.

The conditions available in your project are governed by the file(s) in the Conditional Text folder of the Project Organizer. Unless you are an advanced Flare user, you shouldn’t need to add an additional file to this folder. You can just modify the Default conditional text file.

To modify the Default file, double click it in the Conditional Text folder of the Project Organizer. Here you can add a new condition, or change the conditional text background color. This is the color that will be applied to the text, paragraph, or topic that contains the set condition.

As with variables, don’t change the name of a condition after you have added it to a topic, or the conditions won’t build correctly for those topics.

Save your changes by clicking the Save button on the application tool bar.

Now you are ready to apply the conditions to your content.

To add a condition to a character or partial paragraph in Flare:

1. Open a topic, and select some content.
2. From the Format menu, select “Conditions…”
3. Select the condition you want to apply to the content.
4. Click OK.

The selected content will have the background color for the condition that you applied. (If you don’t see it, be sure you’ve enabled the “show/hide conditional text indicators” option on your XML Editor tool bar.)

If you apply more than one condition to text, you will be able to see both condition colors in the background in a checkerboard pattern. If you don’t see both condition colors in this pattern, see the Note at the end of this post

Let’s say you have the following text (I’m include my conditions in brackets; this isn’t the exact code Flare uses, but it is easier to read and is close enough for the purposes of this discussion):

[Conditions="PrintOnly"]Jack and Jill went [/Conditions]
[Conditions="OnlineOnly,PrintOnly"]up the hill [/Conditions]
[Conditions="OnlineOnly"]to fetch a pail [/Conditions]
 of water.

If my output includes no conditions settings, I’ll get the following text in my output:

Jack and Jill went up the hill to fetch a pail of water.

If my output includes the “PrintOnly” condition, but excludes the “OnlineOnly” condition, I’ll get the following text in my output:

Jack and Jill went up the hill of water.

If my output excludes the “PrintOnly” condition, but includes the “OnlineOnly” condition, I’ll get the following text in my output:

up the hill to fetch a pail of water.

Notice that the text “up the hill” has both conditions applied to it. If any condition is included in the output, the text will be included, even though another condition has explicitly excluded the condition. The include setting trumps the exclude setting. (See Note at end of post.)

To add a condition to a paragraph-level element in Flare:

1. Open a topic, and right-click on the element’s block.
2. From the context menu that appears, select “Conditions…”
3. Select the condition you want to apply to the content.
4. Click OK.

The selected block-level content will have the background color for the condition that you applied. (Again: if you don’t see it, be sure you’ve enabled the “show/hide conditional text indicators” option on your XML Editor tool bar.)

When using block-level conditions, if you apply two conditions to a block, you’ll see a checker-board mix of the condition colors, so you can see that multiple conditions apply. Remember: if your output includes any of those conditions, the block will be included in the output, even if the other condition is explicitly excluded.

To add a condition to a topic in Flare:

1. Open the Content Explorer.
2. Select a topic (or a folder).
3. Press F4 (or right click on the topic, and select Properties).
4. Open the Conditional Text tab.
5. Select the condition you want to apply to the topic/folder.
6. Click OK.

The selected topic or folder will have the condition color appear in the box next to the topic title in the Content Explorer. If you apply more than one condition to a topic or folder, you’ll see multiple colors in this box.

When you exclude a topic from a target, then that topic won’t be copied when the target is built. This can be important if you are providing the files to your clients and you don’t want them to have copies of the files that are only included in the “advanced” version of your project. (It is important to note here that all files in the project are included in all online output versions if they aren’t excluded at the topic level. This allows you to link to files in your help system, even if they aren’t listed in your TOC.)

Conditions can get a bit complicated, and I hope you’ve been able to follow through to the end on this one. It is, however, their complexity that allows them to be powerful tools in your content reuse tool box. You will notice that I’ve not discussed snippet conditions in this discussion. I think Snippet conditions are different enough from your standard conditions, that I want to discuss them in a separate post to try to keep their differences separate. Suffice it to say that there are even more options for conditions with your snippets (new functionality in Flare V3.1).

Now you have the power to use variables, snippets, and conditions so you can use a single source for your content and still publish it in multiple formats, with different content depending on the output. This is content reuse at its finest!

Come back tomorrow and we’ll talk about a sample project where we put all of this together to create several separate output products using the content reuse skills we’ve been discussing in this series.

Day 5: Wrap-up

—

NOTE: This is an update to my original post, which corrects some information I originally included. When you apply the condition settings properly, the INCLUDE condition trumps the EXCLUDE condition. In order to apply the settings properly, you must select each chunk of text separately and apply the conditions to it.

In our example, you would select “Jack and Jill went” and apply the PrintOnly condition. Then you would select the “up a hill” and apply both conditions. Then you would select “to fetch a pail” and apply the ScreenOnly condition. When you have done this properly, you will see a checkerboard background comprised of both colors. That is how you know you applied your conditions correctly.

Instead, if you were to select “Jack and Jill went up a hill” and applied the PrintOnly condition, then selected “up a hill to fetch a pail” and applied the ScreenOnly condition, you would have applied the conditions improperly. The background would only show one color, and the conditions will not be applied correctly in your output.

The tip here is to watch the background. If you see the checkerboard background with both condition colors, you’ve done it correctly. If you don’t both colors in the background, you’ve done it wrong.

(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, 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

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

Yesterday I gave an overview of what content reuse is, and why it is important, and who should use it. Today we are discussing a specific way MadCap Flare allows you to reuse content: variables.

I start with variables, because they are a simple concept that is probably quite familiar to you. Snippets, which we discuss tomorrow, are like advanced variables, so it is important that we have a basic understanding of variables first.

If you have worked in FrameMaker, or have done any programming, you are already familiar with the concept of variables. A variable is code that you insert in your Flare topics that gets replaced when the project is built (prepared for output; when you develop content in Flare, the content isn’t in a usable form until you build an output).

For example, you might use a variable in your project to represent the product name or version number. Every time you want to use the project’s version, instead of typing in the version number, you insert the version variable. When the version changes, you modify the variable in one location, and the project is instantly up-to-date. No more find-and-replace projects where you hope you catch every reference.

Suppose you have a product that gets re-branded and then re-sold. I once worked for a company that created portal software for educational institutions. Each school branded their portal. Using variables, you can refer to the portal name generically, and create a separate output for each client with their portal branding information in the variable settings.

So, how do I use variables in Flare? Keep reading.

Flare groups variables into Variable sets. They are accessed (or added) in the Project Organizer, in the Variables folder. By default, your project contains a variable set called “MyVariables.” You can right-click on the Variables folder to add a new variable set, or you can just double click “MyVariables” to open the generic set. (For starters, it is probably easier to just use one variable set, instead of trying to incorporate multiple variable sets. Multiple variable sets is an advanced topic, not covered in this series.)

By default, there are two variables in MyVariables: CompanyName and PhoneNumber. Click the New button to add a variable to the set. Click in the Definition cell to change the variable’s definition.

So if you want to add a variable for your product Name, you would do the following:

1. Click the New item button.
2. Click in the Name cell (on the word NewVariable). Replace NewVariable with the name of your variable (in this case something like ProductName)
3. Click in the Definition cell. Type in the variable definition (like ACME Explorer).

If you want to add a separate variable for the version number, you’d just repeat the steps, but change the variable name and definition.

When you are editing a topic, you insert your variable by using the Insert menu, and selecting Variable.

You’ll see two variable sets: MyVariables and System. The MyVariables set contains all the variables you’ve set using the process described above. The System variable set contains variables like Date, and page number (for use in printed output).

Select the variable set that contains your variable, then select the variable you want to insert. Click OK. The variable is added to the topic at the cursor’s insertion point.

There is your introduction to variables in Flare. I highly recommend that you use variables in place of all your content that may change from release to release. I use the following variables in my projects:

• Company Name
• Windows installation directory
• Linux installation directory
• Product Long Name
• Product Short Name
• Product version

And before I set you lose creating variables to your heart’s content I leave you with a word of caution: If you change a variable’s name after you’ve inserted it into a topic, the link will break, and the variable will no longer be updated in those topics that contain the old variable name. Once you’ve inserted a variable into your topics, don’t change the variable name. (Obviously you can change the definition; that’s the whole point. Just don’t change what you CALL the variable, or the variables that exist in your project will break, and you’ll end up doing some fancy find-replace to update/fix the problem. Think about what you want to name your variable, and then don’t change it after you’ve begun inserting it into your project!

Tomorrow I’ll be back with information on Snippets–basically longer variables that can contain formatted text, images, etc. See you then!

Day 3: Snippets

Today I start a series of posts on how you can re-use content in MadCap Flare. This is a five-day series. It covers:

• Day 1: Overview of content reuse (this post)
• Day 2: Content Reuse In-Depth: Variables
• Day 3: Content Reuse In-Depth: Snippets
• Day 4: Content Reuse In-Depth: Conditions
• Day 5: Content Reuse Wrap up: Putting it all together

Before we can talk about how you can reuse content in Flare, I thought we should first discuss what content reuse is, why it is important, and who should use it.

What is “content reuse”?

These days it seems you can hardly open a technical communicator journal or listserv without quickly encountering a discussion of XML, which usually discusses the power of single sourcing. These buzzwords (”single-sourcing” and “content reuse”) are tech speak for methods that allow you to write content once, and then reuse it more than one way.

A simple example of content reuse is writing help content, and then using the same source files to produce both printed guides as well as some type of computerized help.

When you modify the source files, you can re-publish both the printed and on-line versions. Since you are using the same source files, the output files are always in sync.

Why is content reuse important?

This “single sourcing” of content is extremely beneficial because when you are managing several projects with hundreds or thousands of pages of documentation, you don’t want to be changing the same content in multiple locations. It is too easy to introduce an error in one version, or worse yet, you can forget to update all the separate locations. If that happens, then you have one version (maybe your printed guides) that have the correct information, and another version (say your online help) with incorrect or outdated information.

XML has become a war cry for technical communicators because it separates the content from the presentation in a way that allows you to reuse content easily. Since the content in itself is basically a bunch of text, I can import that text into an online help system and apply formatting specific to the help system. Then I can take the same source content, and export the text into a PDF file with PDF-specific formatting. If I structure my XML properly, it becomes very easy to take portions of my source text and publish it in an abbreviated format that can be displayed on a PDA or a cell phone screen. The underlying content is the same; the XML source text is just converted into one of several possible outputs, and stylized for that specific output type.

If you are using an XML-based development system, it is also very easy to import other XML documents into another document. If I have a procedure that is repeated over and over, I can store just those common steps in a separate XML file and import it as many times as I need to into as many other XML documents as I want. If the procedure changes, I just update it in a single location–a single source. (Granted, there are several non-XML based tools that provide similar functionality, but that is outside the scope of this discussion.)

Who should use a “single-sourcing” solution?

You should consider a single-single sourcing solution if you are developing the same content, or substantially similar content to be delivered in more than one output. Your outputs might be two guides that share content (say a beginner’s guide and an advanced guide on the same topic that share some of the same content), or your outputs might be in different media formats (one printed and one online). If you create a custom version of your help system for separate clients, single sourcing is the perfect way to ensure all updates are included in every client’s help system.

Really, content reuse is important for you if you provide content in more than one format, or in multiple deliverables. Content reuse obviously isn’t worth much effort if you are only producing one guide in one medium, as there isn’t much need for “reuse” in that situation.

Conclusion

I hope you can see how powerful content reuse can be in a technical communicator’s tool box. If you are only editing content once, but it can be used in several locations over and over, you are able to work faster, more efficiently, and you are less likely to make mistakes. Who wouldn’t want that?

I hope you enjoy this series on how MadCap Flare allows you to reuse content in powerful, granular ways that have made my help products better and more professional.

As a side note, this series is not meant to compare Flare to any other HAT. I don’t have experience with other HATs, so I can only talk about Flare. Many other HATs provide similar functionality, and you should always evaluate all your options before deciding which HAT you are going to use.

Day 2: Variables 

So it’s been a while since I posted much on Flare. For a while I wasn’t using Flare in my daily work flow; I’ve actually moved all new development on the four product lines I support into my Flare work flow, but we keep needing to go back and do dot releases on an older version of our software. When I thought it was only going to be one dot release, it didn’t seem prudent to move the source into Flare. Now we’re working on the FIFTH dot release. Seems I should have made the switch. Oh well.

Anyway, for about a month now I’ve been back using Flare full-time again, and I’ve really been enjoying some of the features in the 3.x line. I didn’t really delve much into them when 3.0 first came out, so many of the new 3.0 features I’m only starting to use now in 3.1.

In any case, here are my favorites so far:

Running Headers/Footers in Word Output

One of my big complaints about InDesign compared to FrameMaker was that InDesign didn’t have an elegant way of allowing running headers and footers in your printed output. A running header/footer means the header/footer’s content changes to reflect the section of the documentation you are in. So a running header might automatically contain the name of the chapter, and a running footer might contain the text of the most recent H1 or H2 style in the document. This makes the printed document much more accessible, easy to read, and professional.

Flare 3.1 gives you the option to use running headers and footers on your Printed Masterpages. You add a variable set to your Flare project that defines the heading styles you want to grab as the header/footer text, then you insert those variables into your Masterpages.

The result is exactly what I asked for. Then I found out, I didn’t know what I wanted.

See, the running headers/footers work great if you stick to a rigid format (a-ha! the structured authoring debate comes again!) in your document structure (e.g. H1 style for chapter title; H2 style for section heading, etc.). I thought I had done that. When I created my printed output, I realized that I have certain sections in my Flare WebHelp that I have as drop-down heads. The style of the drop-down heading matches my H2 style, so in the printed output, you can’t tell whether the WebHelp uses an H2 or used a drop-down head.

That works great for masking the non-standard structure, but Flare can either use the most recent H2 in the footer, or it can use the most recent drop-down head in the footer. I have to go back to my documents and re-structure them so they are all structured the same in order to use running headers and footers in my printed output.

I don’t blame Flare for that, though. I need to pick a structure and stick with it. It’s not Flare’s fault I’m using two different structure formats in different topics.

I give the running headers/footers in Word feature two thumbs up. Thanks MadCap!

Source Control Integration from within Flare

A new feature in Flare 3.0 was source control integration from within the Flare interface. This is a cool feature that I didn’t know I needed, but one that I like the more I use it.

Flare provides direct integration with Microsoft Visual Source Save and Microsoft Team Foundation Server, and provided third-party integration with other source control systems that use the MS SCC API interface. My documentation is stored in an SVN repository, so I had to purchase a third-party plugin to get Flare to work with my source control system. (I bought my plugin from PushOK software, a vendor out of Russia. It cost me 600 Russian Rubles, which came out to about 25 dollars. I’ve been using the plugin now for a couple of months, and it works fine for me.)

I have only a few complaints here: I wish Flare supported the most common formats natively, so I didn’t have to purchase the plugin separately. And I don’t love how for some actions (like moving a folder of topics to a different location in the tree) it seems that either Flare or the plugin checks in each change as a separate revision in the source control. (I suspect this is the plugin’s doing.) Also, I purchased the plugin for one computer I use for editing the project (my main computer) but I didn’t purchase it for my backup computer. When I edit the project using my backup computer, I have problems because the SVN connection settings are stored in my flare project file, so the project files on my two computers can’t match. I hate having to purchase an extra plugin just for the occasional use of the backup computer, so I’ll probably just ignore the inconsistent settings in my project files.

Basic Style Editor

One of Flare’s strengths is the CSS editor included in Flare. In the 3.x line, they’ve stepped things up a notch by including a basic style editor and an advanced style editor. (The advanced style editor is basically the same editor we’ve seen in previous versions of Flare. The basic style editor is a new concept in 3.x.)

The advanced style editor shows all the inherited and local styles and classes in the style sheet. It also shows all the properties available for the styles and classes and lets you change them. You have quite a bit of control over how much information is shown on the screen; You can limit the styles by group, and you can limit the properties list by grouping by type, showing only set properties, or even a smart list of “relevant” properties–properties Flare thinks you might want to change for that style.

Two areas for possible improvement are: (1) Flare still has a habit of modifying my CSS just because I opened it. Example: for some reason it doesn’t like the asterisk symbol in complex selectors (e.g. ul * ol), and any time I open my stylesheet in Flare, it replaces all my asterisks with a “\00002A” which I guess is code for asterisk or something. (2) There is a toggle button to switch between the advanced view and the simplified view. However, the toggle button text shows you the view you will see if you click that button. So, in the screen shot included here, you’ll see that the toggle button says “Simplified View” even though you are seeing the Advanced View. It’s not a big deal, but it makes for a slightly confusing interface. Not to mention that the Flare help system has to explain every time how to check to see if you are really viewing the advanced view or the simplified view. Simply putting the word “Show” in front of the text would really have made this easier.

Conclusion

I still love Flare. There is a learning curve to get up and running with it, but it is a very powerful tool that in my opinion just keeps getting better and better.

——-

PS: I suppose I ought to post a bit of news (and a sort-of disclaimer). Due to my activity in the Flare user forums, last month I was invited by Flare Support to be a MadCap MVP, and I accepted. I use the pseudonym “DocGuy” in the forums. This doesn’t make me a MadCap lackey; some MVPs are known for speaking their minds in opposition of perceived problems at MadCap. However, I am a volunteer forum moderator for the MadCap Forums, and I am a MadCap aficionado. But I don’t suppose that last bit is very surprising to anybody.