Technically Speaking

This post is for recovering Frame users who have switched to Flare, or users of Frame who are authoring in Frame, but are publishing with Flare.

I’m working on a book that will address importing projects from FrameMaker to Flare/Blaze, and I’d like to get your input on what struggles you had when you were (or when you are) importing Frame files into Flare so that I can address these trouble areas specifically.

Anybody who sends an idea that I use will get acknowledged in the book, and I’ll be sending out two free copies of the completed book to randomly-selected people whose contributions I use.

I’m not a MadCap employee; just an aficionado, so there are no restrictions on who can send me information, or who can win the free copies.

Anything you submit becomes my property to use (or not use) in the book, but I do promise attribution for anything I use.

Please send submit your comments via my website’s contact form. Please use the subject “BOOK SUGGESTION”; that will ensure your submission doesn’t get filtered to my spam box.

Thanks for your help.

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

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.