Archives

This is a presentation I gave at MadWorld 2019 in San Diego. Most of the presentation was a live demonstration, but for reference, here are the slides:

• PowerPoint presentation

I had a recent comment on a post I wrote nearly ten years ago. The post actually earned me a bit of notoriety in the MadCap community. For many years after writing that post, people would see me at an industry conference and say, “Oh, you’re the guy who wrote The Six Things I Hate About Flare.” I would quickly correct them, telling them I was very careful at the time to not use the word hate. In fact, right after my actual post entitled “Six Persistent Flare Problems,” I quickly published a post on “Six things I loved about Flare.” I published in that order, because I wanted people to remember the great things I said about Flare, not the quirks that annoyed me. (Nobody ever commented to me about the latter post though, so that didn’t really go as planned.)

A lot has changed in ten years! As I reread that post I realized that ten years ago, I was using Flare version 3. Since then, there have been annual numbered releases, all the way to Flare v12. Then MadCap changed the release naming scheme, and moved to a year-based name, so we got Flare 2016 r2, which could have technically been called Flare 13, but now MadCap posts the year of the release, and if a new major release is released in the same year, they add the “r2” addendum so you can see what version you’re dealing with. That means with Flare 2017, there have been 11 major release of Flare since my “persistent problems” post ten years ago. That is a lot of time, and A LOT of new features.

Now I am using Flare 2017. For your sake, I hope you are using Flare 2017 as well. I’ve been using it since it was released in January, and I’m exceptionally satisfied with the new features in this release.

In the past, I’ve talked in detail about the new features in a given Flare release. I think in this post, I want to take a slightly different direction and talk about my overall satisfaction with Flare as a technical writing tool, based on over a decade of experience working with Flare, training on Flare, and presenting on Flare to large audiences around the world.

Let me state my opinion right out of the gate: MadCap Flare is hands-down the best help authoring tool I have ever used. Its list of features is extensive, and the breadth and depth of its features is vast. The power of Flare is in its ability to help you reuse content in many different ways. You can write once, and maintain content in one single location, and then use that content in many different ways for many different audiences. Here is a partial list of single-sourcing features in Flare 2017:

• Conditions – You can apply conditions to content, and then you can select a combination of include/exclude commands for conditions for each target that you build. (In the context of Flare, you can consider a target as a deliverable. It is a specific set of content published for a specific audience.)
• Snippets – You can reuse chunks of content endless times across your project by putting shared content into snippets, and then referencing those snippets when you need them in other topics. When you need to make a change, you open the snippet, and the content is automatically updated everywhere you use the snippet.
• Variables – Flare has support for several types of variables, allowing you to specify at the project level, or at the target level what the text of a specific variable should be. This makes it easy to create separate targets for specific customers where you can using the wording and terminology that is specific to that customer. Variables are also useful for items that may be used across the document, but may change over time, like the version number of the product you are documenting.
• Snippet Conditions – An advanced feature in Flare, snippet conditions let you customize a snippet for use in multiple places in the project where the content is similar, but not exactly the same. You can then edit the conditions that are used for the snippet at either the topic level (all snippets in that topic will use the specified condition), or at the point the snippet is inserted (allowing you to use the same snippet in multiple places in the same topic, but with different conditions applied.
• Snippet Variables – A fairly new feature, you can specify the variable text of a variable used in a snippet at the point of insertion, allowing you to set custom text at the point of insertion without having to specify the actual text in the variable definition, making it easier to use a snippet in multiple ways across the topic or project.
• Multi-channel publishing – A Flare staple since the beginning, the number of ways you can publish content is increasing over time. Flare now supports  two flavors of HTML5 publishing, both a traditional tri-pane output and a new “Top-Nav” output that works more like a traditional website. Other targets include direct-to-PDF publishing, XHTML targets, DITA, Framemaker, and Word (to name the most popular).
• TOC-embedding – In my experience, this is an oft-overlooked feature in Flare that allows you to single-source your TOCs and embed a TOC into another TOC. This means you can update the order of topics in multiple targets by editing the sequence in one TOC, and all other TOCS that use that edited TOC will automatically update. When you are working in small projects, this may not be too important, but for clients with larger projects (many I’ve worked with have dozens of TOCs; my main current project has 80 TOCs) this is a real life saver so that content in various TOCs don’t get out-of-sync with each other.
• Project merging – In many writing shops, different groups of writers are working on different parts of a project, and at some shops, documentation may be created for separate projects that need to be merged into a single cohesive help system for customers. Flare allows you to merge project outputs, giving you that single system for customers.
• Screen capture tool that uses conditions and variables from your project –  MadCap Flare ships a companion tool, MadCap Capture for free with each Flare license. Capture is a powerful tool that allows you to not only use conditions and variables in your screen shots (and they automatically get updated each time the project is built!), but it also keeps the content of the call-outs separate from the call-out itself, so you can edit call-outs, replace background images, and even translate call-out text easily at any point in the future.
• Global project linking – If you need to work in separate Flare projects, but you have a core group of files you want to use in all your projects (style sheets, master pages, glossaries, corporate logos, etc.) you can maintain those items in a ‘master’ project, and then you can link your other projects to that master project and import those shared elements. Any updates to the master project will get pulled into the other projects before the other projects are built, so they always have the latest-and-greatest versions of those globally-used files.

And that is just a list of Flare’s single sourcing features!

What else do I love about Flare? Lets talk about the user interface experience. Flare is designed with the technical author in mind, and has many, many features that make creating and updating content easy and efficient. For example:

• Customizeable user interface – Flare’s various windows and panels can be arranged in a virtually unlimited number of ways. If you have a wide-screen monitor or multiple monitors, you will especially appreciate Flare’s interface flexibility.
• CSS-based styling – This is huge. Flare uses CSS for styling both online and print output. While you don’t need to know CSS to use Flare’s editors, the work in the background is being stored in CSS, and you can get in and manipulate it manually, so any CSS you learn (or already know) will help you style your content the way you want in Flare. Can’t figure it out? Look at the literally millions of websites and hundreds of books on CSS to find your answer.
• Multiple editing views – One of the things I fell in love with in Dreamweaver many years ago was the split-screen view where I could see the code and the WYSIWYG editor at the same time. (This may be born of my love of ‘Reveal Codes’ from the old WordPerfect days.) Flare fully supports this. You can view just the WYSIWYG editor, or the text editor, or both at the same time. You can put the windows top/bottom or side-by-side. You can filter your current WYSIWYG editor by conditions, allowing you to see only specific conditions while editing. You can view your WYSIWYG window in print format (complete with pages based on existing page layouts in your system), or in web format (where you can even specify a specific media type). There are a lot of options, so you can work in the way that makes the most sense to you, based on the content you are currently working with.
• Dynamic preview – This is a new feature in Flare 2017, and I love it already. I have an extra-wide monitor, and I love having the preview of my content being updated in real-time while I’m working.
• Context-sensitive right-click – Depending on where you are, when you right-click in a topic you get a list of options. In a table, you get table-specific options. In regular text, you get different options. There are easy ways to insert links and cross references without necessarily looking at the entire list of your topics (a list showing, for example, all open topics, which can be quite useful in large projects).
• Drag-and-drop – When you need to insert content from the Content Explorer into your topic, in most cases, you can just drag the item from the Content Explorer and drop it in your topic. This makes it super easy to add content to a topic.
• Customizable keyboard shortcuts – Flare lets you create your own keyboard shortcuts for virtually every Flare function. I have keyboard shortcuts to apply specific styles, and others to run specific Flare macros.
• Quick search – The main project I work on is big. Really big. Finding a specific topic can be difficult. I can use quick search to find any file in the project quickly and easily.
• Quick-access toolbar – Like many Windows products, Flare lets me  customize the quick access toolbar at the top of my screen. I can even select sub-options (like a numbered list) and put them on the quick access toolbar making it very easy to find and use them.

And this is just a very short overview of what Flare can do. We haven’t even gotten into context-sensitive help, reports, the link viewer, group reviewing options, and integration with source control (including MadCap’s own Central offering). In my organization, we have our Flare project connected to GIT, which is connected to buildbot, so every time we check into GIT, buildbot generates a command-line compiled version of our targets, and copies the resulting files to an internal web server. Our developers and help authors always can view the most-recent content on the internal website, making it easy to review and approve topics.

In addition, I’ve had the privilege of being part of the Flare community forums for many years. That is a great group of people with a wide variety of experience and expertise who are willing to help users with questions that they have. The community forums, in addition to Flare’s excellent support staff, make Flare a very attractive tool because there are willing people who want to help you succeed in your project.

Are there things I’d like to see added to or improved in Flare? Sure there are. For example, I’d love to see Capture profiles stored in the Flare project, so they are available to all team members. I’d love to see more robust content management options for replacing live content on a schedule. I’d like to see a browser-based content review tool (taking MadCap Contributor to be a cloud offering) — something that might make MadCap Central a more attractive offering for a wider user base. I’m frustrated with side-menus in TopNav outputs not being location aware (if you have multiple topics used in the same TOC, only one of them is generated into the output, so the sidebar navigation is only correct for the first place the topic appeared in the TOC).  But these are all things I expect MadCap to continue to improve over time.

If we–from the outside–can judge based on the last ten years, it’s a pretty safe bet that there will be a lot of Flare goodness in store.

In the comments, tell me what features you think will be in Flare in the next ten years (Flare 2027(!), if the current naming scheme is continued).

I’m pleased to announce that I will be presenting a free webinar as part of the MadWorld 2013 Speaker Series in cooperation with MadCap Software.

Please join me on Thursday, May 16, 2013 for “Picture This: Optimizing Images with MadCap Flare and Capture,” a free webinar from MadCap. I will be giving a slightly adapted version of my popular MadWorld 2013 presentation. I received a lot of great feedback on this presentation, and I think this will be a popular webinar.

Register by visiting MadCap’s Live Webinar site.

If you have specific questions you’d like to see answered in the webinar, please leave a message in the comments.

Watch for an upcoming announcement about another free webinar I’ll be giving in June on content reuse — one of my favorite topics.

Its Monday morning, and I’m back in Utah. It snowed last night, which is a pretty stark comparison to the weather a week ago at MadWorld 2013 in San Diego. What a great conference! If you followed my Twitter or Facebook feed you already heard me say that this was the best technical conference that I’ve ever been to. I really hope to be back next year at MadWorld 2014.

So here is my post-conference postmortem.

Hotel

MadWorld was held at the San Diego Hard Rock Hotel, right downtown in the Gas Lamp Quarter. It’s a hip, modern, 4-star hotel. The first thing you saw as you entered the hotel was the floor-to-ceiling backdrop behind the check-in counter featuring the MadWorld 2013 logo in some type of recurring video loop. Right there you knew that this conference was going to be something different.

We checked into our room (Christina and our 7-month old came along for fun) and took the elevator up to our floor. The room was amazing. We had a sitting area with a couch and chair, with a large flat screen television and a stocked mini-bar (not a temptation, actually, because the price of a candy bar started at $4). In the bedroom section, we had a large king size bed — the nicest hotel bed I’ve ever slept in, another large screen television, and a Juliette balcony overlooking the Gas Lamp Quarter. The shower had two heads – one in the standard location and one coming directly overhead out of the ceiling. As a tall person, I especially appreciate showers that accommodate my height, and I loved this shower.

The first night, a small welcome gift arrived in our rooms from MadCap. They gave us a MadWorld bottle opener, MadCap M&Ms, and a welcome card. It was a small touch, but something that just made the day nicer and showed a polished finish.

Additionally, the hotel was literally across the street from the light rail station, and we were able to take the light rail on several occasions to get around San Diego.

Conference Venue

The sessions were all held in conference space at the Hard Rock Hotel. MadCap went all out. Each of the rooms had a color on the printed schedule, and there were colored lights along the walls of the rooms that corresponded to the room’s color. Hard Rock has televisions built into the wall at each conference room, showing you the room schedule  for the rest of the day. At various locations in the hotel, you could also see what rooms were being used by the conference and which sessions were currently being held in which rooms. The chairs were comfortable, and the atmosphere in general was very well done.

If I had two wishes for the conference next year, the first would be to make the presentation screens higher, so that more people in the room could see the whole slide deck; and second, provide conference wi-fi in the presentation rooms.

Sessions

No matter how cool the conference is, the quality of the conference comes down to the presentations that are being given. I’m an advanced MadCap Flare user. I’ve been using Flare since version 2, and providing training and consulting services on Flare since version 4. I have the MadCap Advanced Developer certification, and I’m an MVP in the Flare forums. Yet, despite all I know about Flare and other MadCap tools, I still found sessions I wanted to attend, and I learned new stuff at the conference. There were four tracks ever hour: beginner, intermediate, advanced, and tool agnostic. I generally attended sessions on the advanced and tool agnostic tracks, and I found that the presentations I attended were given by people with excellent domain knowledge and experience. I felt like I was learning from people who really understood their subjects and had relevant, useful information to teach us.

I’d rank the presentation sessions as good to great, and the feedback I got from most people was the same. I didn’t hear a single person talking about a session they didn’t like. (Most conferences do have sessions that people don’t like, but I certainly didn’t hear anybody complain at any point about the sessions, so I think that is a good sign.)

Food / Non-session meetups

MadWorld provided lots of food and good networking opportunities outside of the classroom sessions. There was a full breakfast both mornings with fantastic fresh fruit (including fresh berries, melons and grapes!) and good selections of eggs and meat.

MadWorld provided lunch both days of the conference, and that was very good and gave attendees a chance to talk to each other and get to know one another.

There were mixers on Sunday evening, Monday evening, and Tuesday evening with drinks and appetizers provided by the conference. This was a great opportunity to talk socially with other attendees, as well as MadCap staff, which were everywhere during the conference, which leads me to the next section — MadCap Staff.

MadCap Staff

The MadCap staff were everywhere at the conference. They were at all the sessions, all the non-session events. They had a room set up staffed by employees where you were welcome to bring your project and get one-on-one help with the problems you were facing in your project. They even hosted a session for people to share their complaints about MadCap products–and took that feedback to incorporate requests in their project planning. At the mixers, it felt like MadCap staff were making sure everybody felt included and nobody was sitting alone. In short, the staff were a major part of what made this a great conference.

Door Prizes and Collateral

The door prizes at MadWord were interesting. When they first announced that they had boy prizes and girl prizes, I’ll admit that I was a little bit nervous, as that could go wrong in so many ways. No need to worry, though. The first prize was a “girl prize” and was a very nice, very expensive handbag. The next two prizes were gender specific: one men’s pair and one women’s pair of Prada sunglasses. The next prize was a men’s watch. Then they combined the names and drew several gender neutral prizes, like an iPad mini, a $500 Amazon gift card, and a Microsoft Surface tablet. Finally, they raffled off two custom-made (by Mike Hamilton, none the less!) electric guitars. (They were essentially a Zagg-style invisishield wrap on the face of the guitars — they were very cool. For the two winners, MadCap was willing to ship the guitars to them, since they would be difficult to get home on an airplane.

The conference collateral added to the overall feeling at the conference. The room key cards were emblazoned with the MadWorld logo. Everybody got a MadWorld t-shirt. The Lanyards and badges were very nice and very professional-looking. There were pins to attach to your lanyard for each of the MadCap tools you use. The theme of the conference was everywhere from the information packet to the room lighting, to the “rock star” invitations to the special events.

Presenter perks

As a MadWorld presenter, MadCap flew me to San Diego at their expense, picked up my hotel tab (for an upgraded room), provided free full conference registration, and included hotel VIP service (a special check-in and check-out counter with free drinks, and nightly turn-down service in the room. All I paid for was my airline baggage, and a couple of off-site dinners. That is the nicest presentation package I’ve ever had at a conference.

Wrap-up

I really loved presenting at and attending MadWorld 2013. I can’t wait until the 2014 call for proposals — I’m already getting my ideas ready. I hope that you will join me next year at what I’m sure is going to be another amazing event. Start planning for it now… At the conference MadCap said MadWorld 2014 will again be in April next year. This is one conference I know I’m not going to want to miss.

I am honored to be able to present at the MadWorld 2013 Conference today in San Diego.

This post includes links to the slides, videos, and other content that I used in this presentation. This is meant both for the conference participants as well as all blog readers, giving you a flavor of my presentation today at MadWorld 2013.

Here is a link to the PowerPoint Presentation itself (20 MB, includes videos).

The Content

In this presentation, I covered the following topics:

• How Flare and Capture work together
• Capture Features that integrate with Flare, specifically showing you how you can save time and money and reuse content

Flare and Capture Integration

If you haven’t been using Capture as part of your MadCap Flare workflow, now is the time to begin. Starting with version 9 of Flare, Capture is a free download for Flare customers. I have a couple of screen capture tools that I use, depending on what programs I’m working in, but when I’m working in Flare, I always use Capture. Those times where I used a different tool, then came back and wanted to edit the images, I was disappointed because I had to re-do a bunch of work.

Flare makes it easy to initiate screen captures. Depending on your settings, you don’t even need to open Capture or edit the file in Capture. I’ll show you more about this a little later. Capture allows you to edit your images, and you can edit an image from Flare by right-clicking on an image in a topic and selecting “Edit with MadCap Capture.”

Capture also makes it easy to use conditions and variables from your Flare project in the call outs of your Capture images.

Capture Features

I want to focus on how Capture can save you time and money, and show you how you can maximize your content reuse in Flare.

First, Capture saves you time because you only have to do the hard work of image editing once. You can capture a full-screen image, and then crop it down to a single menu item for use in your Flare project. If you ever need to re-capture that button, Capture remembers where the screen was that you captured,what size the capture was, and how you cropped it. So you can go to the updated page, and take the full-screen screenshot again, and Capture correctly crops the image down to the single menu item (assuming, of course that it hasn’t moved.)

Cropping and Re-capturing

When you crop images in Capture, the original image is never deleted. It is stored in a properties folder next to the final image. So if you come back a month (or a year) later and want to change the way the image was cropped, you can open the image in Capture and click the Crop button. The original image is shown, allowing you to change the way you cropped the image.

I’ve worked with developers who decided a week before product launch to change the whole color scheme of the application. I had hundreds of pages of documentation with call-outs — the works, but my work to re-capture the application was minimal because Capture did most of the hard work for me.

Here is a demonstration video (no audio) of how this works.

First, I capture a screenshot, then I crop it.

Next, I modify the style of the interface I’m documenting.

Next, I come back to Capture and re-capture the image.

This works the same way whether you do it the same day, or at any point in the future.

Resizing Images

Let me show you how you can re-size images in Capture. (Again, no audio).

We start with creating a new capture from Flare and editing it in Capture. When you have a screen capture open, you right click on the image and select File Properties. On the Image Effects tab, change the background scale to change the size. 1.0 represents 100%.  Point 5 (.5) is 50%, etc.

Blurring Sensitive Information

Capture lets you blur information that you don’t want people to read. This is helpful if you are working with confidential production content. What’s great about this, is like other Capture features, if you re-capture the screen again later, the blurring will automatically occur in the same location.

From the image toolbar, click  the Effects button, then select Blur Inside Effect Mode. (If you just choose Blur Effect Mode, then everything BUT the image you draw will be blurred.)

Drag the box around the area to be blurred. Right-click on the blurred area to change the Properties.  (I make sure there is no border around the box, and I change the Image Effects tab to have a Blur Factor above 10.)

Image Classes

When you use images in Flare, be sure to create different CSS classes for different types of images. This allows you to have similar images appear in a similar way.

For example, in this image, I have the exact same image from my project, but with different image classes. One is called “thumbnail”, and one is an image with no image class.

For the thumbnail image, you can see that you get a small version of the image that has a red border around it. This is a visual cue to let the reader know that they can interact with this image. Images in general, with no class, don’t get the border, they don’t get down-sized, and they don’t have any interaction when you hover or click.

Examples I have of image classes are: (1)thumbnail, (2) border, (3) specific sizes.

Image Profiles

Capture introduces the idea of profiles, or commonly used settings, that make capturing images faster and more efficient. This helps you get uniform images quickly and easily, directly from Flare.

For example, let’s say I want all my screen captures to be resized to 300px wide, and have a 1px black border and a drop shadow. I can save all these settings in a profile, and they will be automatically used for all images captured with that profile. Observe:

How does Capture save me money?

First, remember that time is money. Every time-saving feature is a money-saving feature.

Next, like I mentioned before, Capture is a free download with Flare 9. You don’t necessarily need another screen capture tool, so that is more money saved.

Third, if your help files need to be translated, you probably don’t use too many image callouts, because you don’t want to have to re-do every image that has a callout. In Capture, the callout information is stored as XML in a properties file in the same directory as the Capture image. Since this information is in XML, it is easy for MadCap Lingo to package that text for translation. What’s awesome is that before Flare builds a target, it re-builds each image in Capture, so if you change a setting in the XML, that setting will be reflected in your documentation the next time you either open the image in Capture, or rebuild your Flare output.

Finally, Capture saves you money by making it easy to reuse and single-source content.

Tell me more about single-sourcing images

One of my favorite Capture features is the ability to use variables in your image call outs. Since Flare re-builds the Capture images at every build, you can use target-specific variables in your callouts.

Watch this video to see how I use a variable to show the product release number, and how when the variable definition changes, the image automatically updates.

You can do the same thing for conditions. Any box or object on the screen can be conditionalized to appear in some outputs, but not others. You can also apply snippet conditions so that different versions of a picture show depending on which topic the image is placed in.

What about using the same image for Print and Online?

Capture allows you to have different settings for a single image, depending on whether your target is online or print.

Here are the settings I typically use (set in a profile) to differentiate print versus online images:

• Image Effects tab:
  • Background scale: 0.7 (70% of captured size)
• Format tab:
  • Format: PNG (this is for Online output types)
• Flare Print Format tab:
  • Enable Print Format: [checked]
  • Format: TIFF
  • Print DPI: 150

Be aware that by increasing the DPI, the resulting image WILL LOOK SMALLER because you are condensing 92 pixels per inch into 150 pixels per inch. This is a good thing for print for a couple of reasons. First, it makes the printed image look crisper, and second, images on a printed page typically don’t need to be the same size as images on a webpage.  You may want to play around with this setting to get a number that works for you, but for me, this has been a good balance. Then I can change it for individual images, as needed, or if I want different settings for a different type of image, then I create a different profile.

Common Questions

Often people have questions about how to use Capture, so I’ve included some answers in this post.

How do I create image captions for my images?

This is technically a Flare question, not a Capture question, but it is still a good one.

I create a container DIV in my Flare project CSS file. I call it DIV.CAPTION

I use the following settings:

div.caption { font-size: 80%; page-break-inside: avoid; padding: 10px; margin: 10px; border: solid 1px #000; background-color: #d3d3d3; max-width: 300px; /* use standard width of images */ float: right; }

Next, I create a paragraph style to number and style my captions. I use this setting:

p.captionnumber { mc-autonumber-format: {b}Figure {n+} - {/b}; }

Watch how I apply this div and paragraph class.

But what if my image numbers need to include the chapter?

Especially for printed output, you might want to use the chapter number in your figures (Figure 4.3, for example). You can easily do this in the print section of your stylesheet by changing the style:

p.captionnumber { mc-autonumber-format: CH:{b}Figure {chapnum}-{n+}  {/b}; }

For online help, you can do this differently, because you can use the different media sections of the style sheet. Note, however, that if these are done differently, depending on the medium, then you will have a hard time referencing them directly in the help text.

I hope this post has given you some ideas on how you can integrate Capture into your Flare workflow. Do you have questions, or do you want to share your favorite Capture feature? Please share, in the comments below.

 

 

The first MadWorld MadCap user conference is still more than four months away, but I’m getting really excited about it. If you are using MadCap Flare in your work, you should do everything you can to make it to this conference. I’m excited to be a speaker at the conference. I’ll be presenting the following sessions:

Picture This: Optimizing Images with Flare and Capture

Sometimes people wonder: “What is Capture, and why should I use it?” In this session, certified Flare instructor Paul Pehrson demonstrates the power of integrating Capture into your Flare workflow. Learn how to Capture allows you to re-capture old screenshots without re-cropping, and without modifying the call-outs. Discover how Capture call-outs can be translated, giving you greater flexibility working with multi-language projects. Find out how to improve efficiency in your work flow by using Capture Profiles, and re-using the same image in online and print outputs. See how you can effectively use thumbnails, create figure numbers and image captions, and modify your style sheet to support different types of images in the same output. This session is crammed with tons of useful tips that will improve the professionalism of your output, and make it faster and easier for you to deliver. (Monday 4PM)

This is going to be a great session, because I get to show how well Capture integrates into your Flare workflow. I believe images are one of the great separators between good help and great help, so making your images look great is important. I’ll have specific recommendations on single-sourcing images for both print and web output.

Customizing HTML5 & WebHelp: Modern Output Matching Your Company Style

Join veteran MadCap user and Certified Flare Instructor Paul Pehrson for a hands-on demonstration of how you can modify the standard HTML5 output to match your company’s look and feel. Dive deep into the HTML 5 skin file to find out how you can customize the smallest details of how your output looks. We will discuss how the skin file works, with tips you can implement today that will improve your output. Then we’ll discuss the use of modern webfonts to get advanced typography in your output, cover how you can create responsive layouts for mobile devices, and dramatically change the way HTML5 looks in the browser. Note: Participants will be given a URL to download all the code shown in the presentation. (Tuesday 1:30PM)

I’m quite excited about this session, because I am going to introduce the idea of responsive design using media queries in your CSS style sheet. This is going to be a very information-heavy session, so you’ll want to come to get an idea of what you can accomplish with a few relatively minor tweaks to your CSS. Don’t try to write it all down, though, because I’ll have copies of the slides and the code I used for session participants.

Oh, and a hat tip to my esteemed colleague, Tom Johnson, who posted descriptions of his MadWorld sessions to his blog last week.

I posted today to the TECHWR-L list in response to a question about the types of files in Flare. There seems to be some confusion about whether or not Flare uses XML or XHTML or HTML files. The short answer is “yes.”

Here’s the long answer.

When we talk about file types in Flare, there are really three different types of files:

• The topic source files (where you edit your topics).
• The supporting source files (where you edit things like alias files, CSH links, glossary terms, page layouts, etc.).
• The compiled help topics (that you copy to your production server, after you build your output).

First, let’s talk about what XML files are, and then we’ll describe each of the above categories.

XML is, (very) simply speaking, the parent language of all markup languages. Anybody can make a “flavor” of XML by defining which tags are allowed in their version of the language. A DTD or schema is a document that says which tags are allowed and/or required, and what order those tags have to appear in (if order is important).

So, a completely valid XML markup language could be the following:

<book>
<chapter title=”Under the Sun”>
<section>
Lorem Ipsum dolem or whatever.
</section>
</chapter>
</book>

Even people who know very little about HTML will know that you don’t have a <book> element in HTML. But you can create a valid XML-based language where <book> is a totally valid element, and any XML editor will allow you to create more <book> elements, even if the XML editor doesn’t know how to render the <book> element.

That is why people say HTML is one type of an XML-based language. There are valid tags:

, and there are invalid tags . HTML editors work because they know what each of the valid tags _do_.

Flare’s files use an XML-based markup language that is very similar to XHTML. We’ll talk about the differences in a minute.

Now, let’s look at each of the types of files I identified above.

First, topic source files. These files are based on Flare’s own XML-based language. This language, as I just said, is very similar to XHTML, but there are several key differences. For example, if you want to include a cross-reference in your topic, or a drop-down hotspot, those require tags that aren’t part of valid XHTML. So MadCap created their own XML language that allows you to do this. The files are still plain-text files; you can open them in any text editor or XML editor, and you will be able to see all the tags. And if you know a bit about Flare’s functionality, you can write the code yourself. You don’t have to use the Flare editor. In fact, if you just copy in pure XHTML code, it will render in Flare pefectly. You just won’t have the additions that Flare added to its own markup (like cross references, index entries, etc.).

The supporting source files in Flare (files that make the table of contents, the target definitions, glossaries, condition definitions, the page layouts, the master pages, the alias entries, the CSH-mapping, etc. etc.) are also in an XML format. These are NOT XHTML based, because they don’t function at all in a way XHTML was designed to work. Instead, these are based entirely on a MadCap created schema. If you understand the schema rules, you can also alter these by hand in a text editor or any XML editor. However, as with ALL XML-based files, you need to be careful, because if you make a change that the schema doesn’t understand, the file breaks. So while you CAN change these in a text editor, you usually will only edit these in Flare because Flare prevents you from messing up the structure of these files.

I think it is important to note that these supporting files are in an XML format, because it allows you to do several things. First, you can check your entire project into a source control system, and you can manage the files easily there. While you can obviously check binary files into source control, checking in text files (like these) makes history tracking, version tracking, and management much simpler, because you only store the diffs, not the entire source file every time you check the file in. Second, it gives you the flexibility to edit the source files in an external editor when you need to. I’ve used this ability on occasion to search through all the text files in the project to look for and replace a specific term (like a product name). I can check every file in the system for the name because every file is a text-based file I can open in Notepad (or whatever). I can even use a tool like TextPad and use regular expressions to make site-wide changes very easily.

One last note on items in this grouping: one type of supporting file MadCap uses is with it’s Capture tool. When you make edits or annotations to an image in Capture, the changes are stored in a .props file in the same folder as the image. That means that when you are doing site-wide find-and-replace, you can even find and replace image annotations in your screen shots. The next time you generate your output Capture generates new images based on the new data, and includes them in the Flare output. For translators, this means that you can translate all the text in screen shots without even needing to open a screen capture utility. You just translate the data in the .props file, and upon the next build, the translated text is now in the screen shot.

The last category I described above is topics in the compiled help system. In this case, I’m talking about WebHelp, since it doesn’t make any sense to talk about Word output file format in the context of this discussion. Your generated help files are HTML-based files with the supporting javascript files to do the whiz-bang DHTML-style effects. Items such as cross references or index entries (that are part of the XML that Flare recognizes) are still in your output, but since the HTML schema doesn’t recognize them and know how to display them, it ignores them. If you were to run Flare’s output through an HTML validator (a tool that compares the markup to the schema to see if all markup matches the schema), Flare’s output wouldn’t validate, because it includes those extra tags, but all modern visual browsers just ignore tags they don’t understand when they build the page. So, in effect, you have HTML output. (Honestly, I don’t know what screen reading software does with non-valid HTML tags, so I don’t know how Flare output works for visually impaired users who use a text-to-speech browser to navigate the web.)

Sorry for the novel. But as I read this thread, I realized that not everybody understands the terms we bandy about like “XML”, “XHTML” and “source files.” I hope this explanation shows that there really are three distinct types of files used by Flare, and I hope you can see how they are all technically “XML”, some are a modified “XHTML”, but all the output files function like “HTML” in the browser.

Clear as mud? Ask in the comments, and I’ll try to clarify any questions you have.

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.