Technically Speaking

(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

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.

So it has been quite a while since I checked in here at TS; a little over a month actually. After my last post, I was in quite a hurry to finish a project at work so I could leave on vacation. Then I took a two week vacation back east, which was wonderful. When we got back, I was swamped with a new project at work and other personal responsibilities. There seemed to be so much going on, that any attempt to blog would require recounting everything so it was easier to say nothing. Well, now I’ve just decided to move on and move forward without trying to catch up on the stories I missed. Oh well.

On the personal front, our little boy has started pulling himself up on things. Its quite adorable, but we found out how un-baby-proof our house actually is. We’re rushing like mad to try to organize things around the house to make it so we don’t have to worry every ten seconds that he is getting himself into something that is hazardous or dangerous. I’m trying to figure out how to attach bookcases and such to walls to they won’t tip forward if a little body tries to climb on them, and we’re getting all the safety devices to keep little fingers out of plug sockets and curious eyes and hands out of dangerous cupboards.

On the professional front, things are going well with work, but I haven’t had a lot of time to work with the new Flare 3.0. I had to work on an older branch of my documentation that is still being done in FrameMaker, so I set Flare aside for a while to keep the older branch moving. I expect to be using Flare again in the next couple of weeks as I make updates to my project that is already in Flare. By fourth quarter I should be doing full Flare documentation, which will be nice. It’s kind of frustrating to bounce back and forth between authoring tools. I get so used to the way Flare does things, and I feel so limited by the way Frame does them (especially since I’m using Frame 7.0; and no, I don’t plan to upgrade to Frame 8 because I’m migrating away from Frame as my primary authoring tool).

I still need to get back to my series on structured authoring. It is coming soon. I think it is a valuable topic, and a discussion of tools will be useful for other technical writers who are trying to understand the concepts.

Anyway, I’m back, and I’ll be posting again soon. Thanks for waiting.

Last week I posted on six persistent problems I’ve found in Flare, a help-authoring tool (HAT) created by MadCap Software.

You may not be able to tell from that post, but I absolutely love Flare. I think it is a fantastic product. Truth be told, I’ve only used two HATs, Flare and RoboHelp X3, so my experience is understandably limited. However, I’m so pleased with Flare, in general, that I’m not even interested in considering other tools.

Also, since my experience with other HATs is limited, I’m not comparing Flare to any other HAT out there. If you are interested in comparing HATs, I recommend the HAT Comparison Matrix provided by the folks at helpstuff.com.

Ok. On to the meat of the post. Today I want to talk about six things I love about Flare (in no particular order).

1. Single-sourcing

At my last job (without Flare), we used a home-grown web-based help system for our product. If you wanted the same paragraph of text in two different topics, you had to insert it separately in both topics and hope that whoever came along to edit the paragraph later made the same change in both paragraphs.

Flare provides a feature called ’snippets’, which are chunks of text that can be imported into any topic. To change the text you open the source file and make the change, which automatically populates that new text into all files the use that snippet. This has been a lifesaver in ensuring that similar features that share steps are consistent as they are described across topics.

I also really like the way Flare implements variables. (”Wait!” you say? “Didn’t you list Variables as one of the persistent problems?” Well, yes. But hear me out.) What is really powerful about variables with Flare is that you can set your variable definitions as part of your target definition. That means that you can set your variables when you create your target definition file and not worry about them again. If, for example, you are providing your help system to two different clients who each use specific terminology they want in the help system, you can just define that terminology in the target definition. You can continue developing content, inserting variables into the text, knowing that when the final output is built the correct variable will be used for the correct client. Variable implementation isn’t yet perfect, but I really like the model being used and I hope this will become a more robust feature in future versions of Flare.

Conditional text is another way Flare makes single-sourcing a great experience. I’m currently using Flare to create computer-based help as well as printed guides. I am using the same source files for both output types. However, there are some times when I want to say things one way for my on-line help and another way for my printed guides. (For example, suppose you have a sentence that reads “The purpose of this guide is to help you become familiar with Widget.” That works for the printed guide, but for on-line help, I want to say “help application” in place of “guide.”)

Using conditional text, I can include both “guide” and “help-system” and I conditionally mark the text so that the word “guide” only appears in printed output types and “help-system” only appears in computer-based output. I can create custom conditions, so this becomes a pretty powerful feature when combined with the condition settings available in the target definitions.

In short, Flare provides a lot of great support that makes single-sourcing from Flare a breeze.

2. CSS Support for different Targets from single style sheet

Flare is the first product I’ve used that supports different media targets from the same style sheet. This means that I can set the styles for my printed documentation and my on-line documentation in the same CSS style sheet. There is one location that contains all my style information.

I love having my styles based on CSS. One of my major complaints about the 7.x product line of Adobe FrameMaker is the difficulty of managing styles across large books or libraries. With Flare, I set all my styles in the style sheet and the changes are reflected automatically in every topic across the project.

My style information is text-based, so I can edit it in any editor of choice, including Flare’s built-in CSS editor, a powerful tool for editing CSS style sheets (more on this later).

Once I acclimated to using CSS for printed documents, I’ve come to really love it. It is a great standards-based way to ensure consistency across outputs.

One side benefit is that if customers decide to press the print button on the computer-based help application, the resulting printed page uses the “Print medium” settings in the CSS style sheet, so the printed page has the same look and feel as the printed guides. For me, this is very, very cool, and it is one of the things I love best about Flare.

3. Integration with Capture

Flare has tight integration with Capture, a MadCap product used for images and screen shots. While Capture is only a version 1 product, it is still a powerful tool that I’ve learned that I can’t live without. I am really looking forward to future versions of Capture to see how it improves.

The integration with Flare makes working with images really easy. With Capture, I can set different properties for images based on whether they will be used in printed output or on the web. For example, this allows me to have my images in the printed guides be .png images and the images in the online version be .jpg images.

Changes to images in Capture are stored in layers above the image, so you can change the underlying image while keeping the text or other alterations (including cropping) that you made to the original image. Since Capture also integrates with Flare variables, when I include a variable as part of the text on my image, that variable changes when the help system is built to the variable setting determined in the output target definition.

Capture also allows me to re-capture images, and depending on your settings, remembers the original image size and location (which you can re-size and move, as needed), so you can re-capture images late in the development cycle. This saved my bacon on a recent project when UI changes were happening the day before the scheduled release. I could re-capture the images while retaining all the modifications I’d made on the original image. I just replaced the bottom layer original image with the new one. This literally saved me hours of work at the end of the project when every minute matters.

4. Design of Tool

I love the way Flare is designed. While it may not be totally intuitive for new users, the more I learn about Flare, the more impressed I become with the smart design decisions made by the developers. Here are some UI features I absolutely love.

XML Editor

Flare’s XML Editor is top-notch. The editor gives you the ability to view “blocks”, which are really representations of the XML parent-child element hierarchy. The blocks appear on the left side of the editor. You can interact at the block level, collapsing blocks so you only see the parts of the document you are most interested in, or dragging them to a different position in the document.

The blocks are a powerful way to see nested tags and work with blocks of code, including paragraphs, tables, lists, etc.

The editor is the first I’ve seen that lets you toggle parts of the view space from a WYSIWYG view to a code-view; in fact, Flare lets you switch to a type of code-view for individual XML elements while retaining the WYSIWYG view for the rest of the topic you are editing.

If the source file changes while you are working, it is automatically updated in the Flare editor. For example, if you are working with a topic and you decide you want to edit the actual XML code, you can open the text in an external editor (any editor of choice) and make your change. When you save it, it is automatically updated in the Flare editor, so you are always working with the current copy. This is true for all content in Flare, including images.

I could go on. The XML editor in Flare is powerful. I’ve never seen anything quite like it.

CSS Editor

If you have worked with CSS style sheets, you know how hard they can be to maintain. Very quickly they get long and complicated. When you want to edit a style, you have to search through the CSS to find the particular style, then you have to know the proper syntax for getting the style you want. Well, Flare has made that process much, much simpler with their powerful, flexible CSS editor. The editor shows you the elements in your project that you can set styles for, and gives you a list of relevant styles for that element. You can change the grouping to see the available style settings grouped by property groups, relevant styles, or even those styles that have a value set for them. This CSS editor is better than any stand-alone CSS editor I’ve used, and makes creating styles across multiple media types a breeze. Once I started using the CSS editor, I wondered how I ever did CSS without it.

Flexible layout

Flare’s designers seem to have gone out of their way to make the workspace as flexible as possible. It seems that every window can become a pane, and vice versa. Windows can be detached from the workspace (a great tool if you’re using multiple monitors for authoring), as can panes. You can dock items to any of the four sides of the workspace. You can then save multiple layouts that you can reopen later. This is particularly handy because often different types of work are easier with different layouts. So when you are writing new content you can have certain windows and panes in one arrangement, while easily using a totally different arrangement for indexing. Find the layouts that work for you and save them, so you can spend less time trying to get the windows just right and more time authoring your content.

I could go on. The tool is well-designed by people who obviously have thought a lot about how help authors work. Once you get accustomed to the workspace and the Flare way of doing things, you really begin to appreciate the beauty of how Flare is designed.

5. Support from MadCap

Madcap support is fantastic. These are people who are very interested in getting it right, and work to ensure that problems are understood and addressed.

After my last blog post, I actually received an e-mail from MadCap support wanting to know if they could call me to discuss some of the problems I reported. Imagine somebody from Adobe wanting to call you to talk about the problems you’re encountering with PhotoShop or FrameMaker. Keep imagining, because it ain’t gonna happen. MadCap provides forums where users and MadCap support employees troubleshoot problems poised by other MadCap customers. Customers who purchase maintenance agreements also have additional options for obtaining support. We have an e-mail based maintenance agreement, and I am amazed at how quickly support has responded to my problems. They haven’t been able to fix every problem I’ve sent yet. But I believe they are working on them. I believe that they care about the customer’s experiences and want the experience to be a good one. They go out of their way to ensure that customers are happy and things are going well.

The care they show their customers engenders loyalty in return. I can put up with some persistent trouble in the application when I believe that the provider is taking my concerns seriously and will work to improve them.

6. Implementation of standards-based, plain-text files

I also love that Flare uses standards-based project source files. All of the project files are standards-based, non-proprietary formats. Most are XML-based, with a few exceptions (.css style sheets, document header files for context-sensitive help, etc.). However, I know that my content isn’t being held hostage by MadCap. As the years go by, if I need to migrate to a different HAT, I know that my content will be accessible.

Since the files are plain-text, not binary, they also work nicely with source-control software. When I make changes to a file, the source control can track which changes were made, rather than storing a whole new copy of a binary file. My entire project is 16MB, of which 15 MB are images. This makes for much more efficient storage on the source-control system.

In short, Flare is a fantastic help authoring tool. It is my tool of choice. If you are developing help content, you owe it to yourself to check it out and see if it is the right tool for you too. I think you’ll be glad you did.

I am. Every time I come to work.

As I stated in my last post, I’m a Flare user, and I really, really, really like Flare as a help authoring tool (HAT). It’s a solid program that does a lot of great things. On my recommendation, my company is going to renew our maintenance contract with Flare this fall, and I expect to be using Flare for a while to come.

That said, I think that there are a few persistent problems in Flare that new users should be aware of when they start using the product. None of these are deal-breakers for me, even in the aggregate. Still, I think that these are things that if I had known were problems, I wouldn’t have spent hours banging my head against the wall trying to solve them.

Thus, for the new Flare user, I present Six Persistent Flare Problems that you should know about when using MadCap’s flagship product.

1. Cross Referencing Problems

Flare’s implementation of cross referencing on the surface is really cool. When I want to link to another topic in my project, Flare inserts a cross reference link. When the project is built, if the target is computer-based, then Flare just inserts a standard link. If the target is print-based (Word or FrameMaker), then Flare inserts the text of the link, but adds “on page X” so your readers can flip to the proper page in the printed manual.

However, the persistent problems with cross referencing include the following:

• If the title of the target topic changes, the text of the cross reference link doesn’t. Somehow, I’d like Flare to track the topic that I’m linking to, and if I am using the topic’s title (or any heading level, really) I want Flare to know that the text changed and reflect that in the topics that link to it. (Edit: 7.11.07) It turns out that this does work like I want it to. When you build the project, the cross references are updated in the output. The source files aren’t updated in the Flare editor, but the resulting output has the correct cross reference titles. You can update the cross references in a particular topic by using the Tools, Update Cross References option.
• Cross referencing doesn’t know if a topic has been excluded from the output. If I create a cross-reference link to a topic, that cross reference link will display even if the target topic has been marked for exclusion from the output. So say I’m using the “lite” version of the software, I’ll see links to all the topics that are only in the professional version. Cross referencing should be smart enough to not link to topics that are marked for exclusion for the output that is being compiled.(Edit: 7.11.07)This works, if you know what you are doing. If you just mark the topic for exclusion in the TOC, then the cross reference is still included. Which makes sense, since the topic is still available in the output, it’s just not listed in the TOC. In order to exclude a topic and disable cross references to the topic, you have to mark the conditional setting in the topic properties in the Content Explorer pane, not in the TOC. When you exclude a topic in the Content Explorer, then cross references to the topic lose their hyperlink, and just the text of the link remains. (However, the text won’t show the most current topic title; it will only show the topic title that the XML editor found last time you updated the cross reference, as mentioned in the previous bullet point.
• In my Word output, occasionally I have a cross references in print that say …”See page 1″ when the target topic is not on page 1. I submitted this to Flare tech support, and they can’t figure out why it is happening. I ended up having to search through my Word doc after it was compiled to find any references to “page 1″ and insert the correct page number. This happened for about 1 in 4 of my cross reference links. (Edit: 12.05.07) I have confirmed that this is still a problem in my Word output using Flare V3.1. MadCap Support reports this is a high priority open issue.

2. Word Output Trouble

Being able to compile directly to a Word file works pretty good for the most part. I love being able to set CSS styles for printed output that are reflected in the Word document. Yet, I still encounter the following problems when using Word output:

• Word ignores CSS spacing (margins and padding) that are applied to tables, lists, and the <body> tag. I don’t know if this is a Word limitation or if Flare isn’t sending the proper info to Word for this, but I have an open help request about this issue.
• Word ignores CSS background images. It simply won’t display them. I haven’t yet figured out how to place text in front of a graphic, because theoretically, in CSS it is easy. However, it just doesn’t work in Word.
• When a topic starts a new chapter in two-sided printed documentation, generally you want this first page to be on the recto, or right page. That’s just where chapters start. In CSS there is a property you can apply to the chapter heading that should make the heading appear at the top of a right page. Word calls this an “odd” page, because odd-numbered pages are on the recto side of the paper. However, when Flare compiles the Word output, new chapters can’t be forced to start on the recto page. They always just start on the next blank page, regardless of whether it is a recto or a verso page. I have an open bug about this one too, as I currently have to do post-processing to make this work properly.(Edit: 12.05.07) In Flare version 3.0.3 and later this has been fixed, as per an article in MadCap’s knowledge base. I’ve tested this, and it works beautifully! The squeaky wheel does get the grease!
• Auto numbering for chapters is funky. I’m not sure how this happens, but in my project, I have to apply my auto numbering characteristics to the chapter before I want the characteristics to appear. So in order to get my Appendix A to have the letter A as its auto number, I have to set the properties of chapter 10 to be “restart numbering, type A”. If I try to do this on the chapter that is Appendix A, the settings aren’t applied until Appendix B. Again, I’ve an open help request on this one.(Edit: 7.17.07) This problem was resolved in Flare V3 which was recently released by MadCap. I even got an e-mail from customer support letting me know that an issue I had logged has been resolved. I’ve tested my Flare project, and it works as you would expect it should with regards to chapter numbering.

3. Variables

Variables are a great way to work with content. Instead of constantly referencing your product name, you insert a variable. Then, if the product name changes, you just change the variable, and build the project, and the variable is replaced throughout the help system. Or maybe you supply the help system to various clients and they are integrating your system with a proprietary product name as part of their project. In that case, you would create different target outputs, and specify the variable name for that target. When you build the project, the variable is replaced throughout the help system.

Sort of.

This works unless you are using the variable in the title of a topic. Topic titles are a special case because they are used for linking (see <Topic Tile>), in the TOC, etc. The topic title is generally a <h1> tag, but can be any heading level you define. When you use a variable in a heading, and the heading is pulled for the name in many cases Flare either omits the variable entirely, or it puts the plain text of the current variable definition in the target text. This means you have to edit your output carefully to ensure that your variables are replaced correctly. (I do a find/replace in Word to see if there are any problems.)

4 . Glossary Problems

Flare includes support for creating a glossary. It also gives you a number of options on how to display your glossary entries, depending on your output options. In computer-based output, you can have every instance of the word tagged so that it becomes a link. When users click on the link, the glossary definition is shown in a pop-up, or as expanding text after the glossary item. You can have this happen every time the word is found, or only the first time it is found in each topic—or not at all. The computer-based outputs give you the option of having a separate glossary pane with the glossary items listed. You click on them to see the definition. And the glossary proxy in printed documentation lets you include an appendix that includes all the glossary terms in your output.

This is a powerful tool, and is a great improvement over Robohelp (at least RH X3 that I used). In Robohelp, when you entered a glossary item, RH searched through the current topics, and actually modified the topic with the glossary entry. If you did this process twice, then you actually inserted the glossary definition TWICE in the output. Flare doesn’t input these until it compiles the project, so you can create the glossary at any time and update it at any time without worrying about how this will affect the content in your topics. However, this also isn’t without its flaws.

First, if you have the computer-based output insert glossary references in your text, it will modify the formatting and text in EVERY glossary item it encounters, or optionally in only the first glossary item in each topic. In either case, if the first time the glossary entry is found is in a heading, the heading gets totally messed up. Flare needs to figure out a way to ignore content in heading tags when it does the glossary compiler.

Second, there is an “undesirable feature” in the way Flare handles synonyms. In the glossary editor, you enter the search term and its synonyms, separated by commas. Then in the next field you enter the definition. This is a great idea. Instead of creating separate entries for “help authoring tool” and “HAT” you can list them together and only enter the definition once. Every instance of either the word or its synonyms is tagged with the definition. This isn’t great, however, when you go to print your printed glossary in your printed output. Flare inserts each synonym as a separate entry in the glossary, with the entire definition. In one of my topics, I had a word with about 4 synonyms, including acronym variations. In the printed glossary, all four words were inserted, in order, in the glossary. I wish Flare could allow me to choose the master glossary term with child terms. The master term would be shown in the glossary, with the definition. Child terms would say “See <master term>”.

5. Win-centric Design

For some reason, MadCap decided to program Flare using Microsoft’s .NET Framework. Thus, MadCap products are tied to machines running the Windows operating system. Now I’m not a programmer, so I’ll admit ignorance on this topic. However, off the top of my head I can’t think of other major products that require you to install the .NET Framework in order to use the product. I also worry that this is a short-sighted decision, as it alienates the ever-growing Mac user base and Linux user base.

I’d love to be able to make the switch to Linux as my primary OS. However, I’m stuck using Windows because it’s the only OS that my tools will allow me to use.

One of the problems with this mindset is it makes the command-line build option pretty useless for me. First, in order to use the command-line builder, you have to have a separate full license of Flare (unless you use your work system as the build machine. But if you are going to do that, why use command line?). Plus, since Flare only works on Windows, your build machine can’t be a Linux machine. Our software does a nightly build, and I want the nightly build to include the latest version of the help system. But I can’t integrate them because our builder is a Linux box and Flare won’t work with it.

Flare needs to provide a command line compiler that works on Linux. Additionally, it would be better if that were a separate utility that I could purchase from MadCap, without having to purchase an entire Flare license just for command line compiler.

6. Misc Items

My final gripes can’t be grouped into one cohesive category, but I don’t think any of them were big enough to merit a separate topic number, so here they are, grouped as “Misc Items”:

• Flare is very powerful. However, its design isn’t very intuitive in a lot of ways. For example, the blocks feature is powerful, but has different unmarked hotspots, where if you click on the block in different areas, you get separate options. This isn’t documented and you just figure it out by trial and error. The menu items are often placed in odd locations, particularly some of the dock items in the Windows menu. Once you know where to look, it kind of makes sense, but searching for them the first time can be tedious.
• When you link to a heading in a topic, if the heading is an expanding text hotspot, the expanding text isn’t expanded by default in the computer-based output. The only way to get this to work is to place the anchor inside the drop-down hotspot, but then you lose the hot spot header.
• When you paste information into Flare, you lose all formatting, including spacing and line breaks. This was really unfortunate when I was manually converting topics from Frame, and I pasted entire topics into Flare. Flare stripped the formatting and the line breaks and inserted the text as one long paragraph. This drove me nuts.
• If I use Flare’s conditional settings to exclude a topic (at the topic level, in the Content Explorer), that topic still gets included in the project’s web-help folders for WebHelp targets. This is a bug, and a major one at that. Since the topic files are stored in the compiled help project as .html files, anybody can go into the source and find the extra topics. If I’ve marked them for exclusion, there is a reason. Flare should respect its own conditional settings and not publish topics that aren’t marked for publication.Edit (6/18/07): MadCap Support contacted me, and together we were unable to duplicate this behavior. I think it was pilot error. When I cleaned my target files, the excluded files were not published. Thanks to Richard at MadCap for helping me resolve this issue.

There you have it. These are the problems that I’ve found with my favorite help authoring tool. In most cases, I’ve figured out how to solve the problems I’ve encountered, and like I said in the beginning, none of these are deal breakers. I still think Flare is the best authoring tool for my needs.

Stay tuned next week for my post on my favorite features in Flare, to give some positive balance to this list of Flare’s problems.

If you’ve made it all the way to the end, thanks for reading. I hope you found my experience helpful as you evaluate Flare as a potential help authoring tool.