Technically Speaking

I have an evaluation copy of MadCap’s forthcoming release of Capture 4. Stay tuned and I’ll give you an review in a day or two!

MadCap Software announced an open beta of Capture V3, MadCap’s screen capture tool. According to MadCap:

Version 3 of Capture builds on the strengths of the initial version of MadCap Capture and dramatically improves cross product integration with the full suite of MadCap Software tools. Additionally Capture Version 3 has added many requested user features, such as Clipboard functionality, zoom while capturing, time delay, improved image cropping, better support for print formats and much more!

Frankly, this couldn’t have come at a better time for me. For several weeks, I’ve been trying to wrestle with how to make my screen captures look better in printed output. I had finally decided to remove all the MadCap Capture images from my project, and replace them with images I’d taken with SnagIT. It wasn’t a perfect solution, but it fixed some of the problems I was having with my capture-only workflow.

However, now I’m using Capture V3 for my screenshots, and I finally have the control I need over both the printed and the online images that are used in my Flare projects, using a single image.

If you want to participate in the open beta of Capture V3, you can find more information in the MadCap forums.

Last week I was interviewed by Tom Johnson for the Tech Writer Voices podcast.

Here is the link to Tom’s podcast post. He’s allowed me to embed the podcast here on my website, so you can listen to it from here if you’d like.

From Tom’s site:

Topics Discussed in this Podcast

* Flare’s XML editor
* Integration of Flare with source control
* How Madcap addresses the entire writer’s workflow
* Generating quality printed output from Flare
* Cross-platform shortcomings
* Thorough integration of CSS standards in Flare
* Flare’s CSS editor
* Flare’s learning curve — how long it takes to learn Flare
* Variables and snippets
* Indexes and insertion of index keywords within topics
* Implementing variables across the entire workflow
* Rewards from being a forum volunteer and moderator
* Madcap Software’s family feel
* Relevance of company size and location
* Mike Hamilton, vice president of product management
* Lingo and the single sourcing of content across images, topics, and outputs
* Lingo’s efficiency with localization
* Madcap’s responsiveness to blog comments and feedback
* Feedback Server and topic-based comments
* Balancing complexity with usability
* Madcap Analzer and Feedback Server
* Product/company image generated by blogs and user forums
* The online help market in 5 years
* Reasons for Framemaker’s stagnation
* Qualities of companies that will succeed in the future
* The best way to learn Flare

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.