I was asked to provide help content in the form of a getting started guide for a piece of software that was going to be released world-wide.

I started working on the project using my tool of choice, a help authoring tool called MadCap Flare. This is a tool I really like, and have been using for several years. I’m something of an expert on Flare, so it is my first choice for pretty much any authoring project.

I started working within my group, however, and found that Flare wasn’t going to be the right solution for this project because of project constraints outside of my control. We have an in-house translation group that does all our content translation. They have their tools in place and are not interested in obtaining and learning to use a new tool (MadCap’s Lingo tool). There are certain strings in the project (specifically surrounding variables and master pages) that wouldn’t get sent to translation if they didn’t use Lingo. This project is going to go out in 24 languages, so simplifying the process is essential.

I ended up creating a site using JavaScript and HTML. Translation can handle HTML files, so this project is easy for them to manage on their side.

The moral of this story is that I ended up picking an inferior (in my opinion) tool, HTML and JavaScript because it was the right tool for this project. While I think Flare is a better tool overall, in this case, it wasn’t the right fit. Now I could have gone through a bunch of hoops to output HTML files and then re-import them into the Flare project, and then try to re-generate the project in the new language, but that was more work, with more room for error, even though it would have given me more options for designing and creating my output.

Sometimes you have to pick the right tool, even if it isn’t the best tool.

You may remember the old WordPerfect days. Those were the days of Reveal Codes (Alt F3) when changing the formatting of your document was easy. In fact, in the late 80s and early 90s, WordPerfect was the de facto standard word processor.

Now, twenty years later, Microsft Word has taken over as the market leader and standard word processor. Word Perfect is still out there, but you’re hard pressed to find any company (outside of Corel, the current owners and developers of WordPerfect) that uses WordPerfect.

Most former WordPerfect users have been forced to learn to use Microsoft Word, and many complain that they are lost without Reveal Codes, and are unable to format the document the way that they want. They believe that WordPerfect was a better word processor. However, just because WordPerfect may be the better tool, it doesn’t necessarily mean it is the right tool to use. It turns out that if you can’t share documents with other people who don’t use the same word processor then you have a harder time communicating with them. Or, if your organization doesn’t support WordPerfect, you can’t use it at work.

(Now, I will point out that current versions of WordPerfect are able to read and write MS Word files, so this isn’t a perfect comparison, yet there have been many people who, due to work requirements, have been forced to make the switch to Word, regardless of WordPerfect’s ability to read/write MS Word files.)

The trick, it seems, is knowing when the right tool IS the best tool, and knowing when the right tool is something else. As technical communicators, we need to be more focused on getting the project done the right way for our organization, while focusing less on whether or not we get to use our favorite tools.

I’d love to hear about your experiences with giving up on tools you loved for the sake of a project. Share your story in the comments, below.

I’ve been using Flare V6 for a couple of months now, and this review is to give you an end user’s review of the features and enhancements Flare V6 has to offer. You may be asking yourself if it’s worth it to upgrade your existing Flare installation to the latest version. Let me give you eight reasons to upgrade, if your budget allows.

Reason 1: WebHelp Mobile Output

Flare V6 includes a new target: WebHelp Mobile. This target creates a web-help output designed for mobile browsers, particularly the iPhone.

If you are trying to produce help content in a way that is accessible in the increasingly-important mobile browser market, this output format is exactly what you need.

To leverage your existing content in this new output format, it is as easy as adding any other target. You add a target to the project, and select WebHelp Mobile as the target type. The first time you add a WebHelp mobile target, you will also need to create a mobile skin. If you leave the default values, Flare creates a skin that matches the native iPhone skin very nicely. (There are actually thee different mobile skins to choose from including gray (default), slate, and green.)

Now, set your skin in your mobile target file, and build your project. In about 30 seconds, you’ve created a mobile-friendly target. The results look great:

Reason 2: Batch Generate and Publish

This is a feature that I needed about two years ago, and I’m thrilled to see it built directly into the Flare interface.

Consider the following use case: you are working on your help system in the same cycle as the developers who are coding the application. Nightly, an automatic build of the software takes place. You want to be sure that the latest changes to the documentation get pulled into the nightly build so they can be tested in the application.

Prior to version 6 of Flare, you had to create a script and run Flare from the command line. Your script would build each target, and then would copy it to the production environment where it would be captured by the nightly application build script. Then you had to create a Windows Scheduler task to run the batch file at a specific time.

If you didn’t know much about coding, you this was a manual process. Flare could build to a “build” location, but couldn’t publish to your “publishing” destination. And it was a manual, outside-of-the-application process.

No more.

With Flare 6, MadCap introduces batch targets. A batch target is pretty much what it sounds like: it is a batch of targets that get built and/or published by a single process.

I create a batch target like I create a normal target:

When I create a batch target, I select which existing targets should be included in the batch. Now I can choose to build all the targets in the batch, publish all the targets in the batch, or both build and publish all the targets in the batch.

What is even more powerful is that you can schedule these batch builds directly in Flare. No need to use Windows scheduler.

It is as easy as adding a task, and deciding when the task should run.

Then, of course, you need to leave your computer on during the build time, because clearly the process can’t run if your computer is not turned on.

Reason 3: Multi-Topic Review

Maybe you’ve heard about using MadCap’s review tool, XEdit, or maybe you’ve actually tried it, but found that it didn’t meet your needs. In any case, now it is time to look at it again, and closely.

Flare V6 now supports the ability to send multiple topics out for review at the same time. In prior versions, if you had a lot of topics to send to a single person, you had to go into each topic and start the review process for that topic.

Say your printed guide contained 15 topics, and you wanted a SME to review the entire chapter at once. You had to send out each topic separately for review.

Now you can open a single topic, click to send it for review, and you get the following dialog box:

Here you can add more topics for review, and then save the entire batch to be sent in a single file to the reviewer.

If you wanted, you can send the entire project out for review in a single file. This is going to make getting reviews more efficient and allow you to be even more productive in Flare.

Reason 4: File Tagging

Closely related (for me at least) to the last reason to upgrade, there is another great new feature that makes working with projects much, much easier: file tagging.

With file tagging, you are essentially creating additional metadata about a topic such as the topics author, the progress of the document through the review process, or any other tag you want to associate with a topic.

As an extreme example, I show how this would be useful by giving a real-world use case. A friend of mine (we’ll call him “Steve”) was recently working on a Flare project. He had seven different authors contributing content to him in Word format. Each document had to go through six different reviewers which included at least 4 different drafts of each document.

Steve didn’t get to choose the process, but he had to manage the flow of documentation through the process and into production. He had to create a massive spreadsheet to track the progress of each document through all the iterations of reviews and approvals. Time was spent every morning getting all the writers together to update the status of the spreadsheet document. By the end of the project at least a cumulative 150 hours had been spent trying to keep track of the status of the individual topics. Multiply that by the average hourly wage of the people who were in the meetings, and you see that somewhere in excess of $5000 was spent in those meetings, simply to track the progress of topics through the pipeline.

Too bad they didn’t have Flare V6. With Flare V6 you now have the option to add tags to individual files. In Steve’s case, he could have added a tag for the topic author, and a tag for each review phase. When a document passed through each phase of the pipeline, the author could update the flag for the topic. With Flare’s built-in reports, Steve could run a report and know instantly where each topic was in the pipeline, where each contributor was in their progress, and provide that report to the managers. There is still some maintenance involved in tracking the individual topics in Flare, but at least with Flare you are doing it in a single location. In Steve’s case, his project could have saved—literally—hundreds of hours, and thousands of dollars.

True story.

Reason 5: Improved Template Management

Have you ever tried to create a template in Flare? Prior to version 6, it was a real pain. You had to go out into the Windows file system, and create your own file structure in a specific location with everything spelled exactly correctly or the template files couldn’t be seen by Flare.

No longer. Now you can create your templates right in Flare and manage them from within Flare’s interface.

Here are three menu options in Flare V6 that apply to this discussion:

File > Save As Template…
Project > Save Project as Template…
Tools > Manage Templates…

The first, Save As Template, allows you to save any item you are working on as a template that you can re-use later, be it a topic, a target, master page, etc.

Next time you are creating an item of that type, the template will be there to choose from.

The second, Save Project as Template lets you save the current project as a template. This allows you to create lots of boilerplate content that you can save at the project level, and have ready and available for each new project that you create. This is handy when Master Projects (available since V4, I believe) are overkill. Sometimes you want to start from the same baseline, but be free to develop a project that is significantly different from another.

Finally, the third, Manage templates, lets you manage all your template files in a single window, so you can see what templates you’ve created and what you still might want to develop or modify.

Reason 6: Link Viewer

My colleague, Tom Johnson, pointed out this feature to me, and I think it is great. In earlier versions of Flare you were able to view dependencies for a given file. The link viewer gives you that same functionality, but more.

With the Link viewer you can easily see what topics link to a given topic, and where that topic links to. You can double-click any topic in the list to go directly to that topic to see if any changes are needed.

For example, maybe in version two of your product, you enhance the widget feature. It now works differently, or is invoked in a different way. With the link viewer, you can quickly see what topics link to the widget topic. Then you can open each of them and see if any text needs to be modified to accommodate this new functionality.

This may seem like a minor feature, but when it comes to making updates to documentation, I think you’ll find that this is really rather useful, saving you mouse clicks, time, and mental energy.

Reason 7: Improved PDF Support

I love the new PDF support in Flare V6. In Flare V4 MadCap gave us the ability to publish directly to PDF without needing Word or Framemaker. In Flare V5, they enhanced this capability and included options for including your own metadata in the document. In Flare V6 you can now add additional metadata and can control PDF security options from within the Flare PDF target editor.

This really makes publishing much easier for me. One of the final, manual processes I always had to do on my PDF documents was to modify the security settings and ensure that all the metadata was set in the PDF document. This was a pain, because in many cases, my PDF was pulled into the build nightly based on the batch process I outlined earlier in this article.

Now with Flare V6 I can set all the PDF settings I need in the target, and with the batch builder and publisher I really can let my automatic, nightly build be released without any post-build work at all.

Reason 8: User Interface Enhancements

Flare V6 has several user interface enhancements that don’t seem to be much individually, but in the aggregate make the whole experience smoother and nicer. For example, the target editor has been updated so that you only see the options that are relevant to the type of target you are creating. Icons have been modified throughout the application to make it easy to identify the different types of files you’re working with (each target type now has its own icon associated with it, for example).

While this probably isn’t a great argument in itself for an upgrade, it is a nice bonus.

Conclusion

In this article, I’ve given you eight reasons why you should upgrade your existing Flare installation to version 6. Flare is my first choice help authoring tool, and this latest version makes me like it all the better.

I’m interested to hear your take, as well. Please comment below and tell me your favorite new features in Flare, and sound off about the features that are missing that you’d like to see added in a future version.

________________________________
Full disclosure: I am a certified MadCap Flare trainer and an MVP in the MadCap user forums. I received a free copy of Flare V6 because of my assistance in the forums, NOT because of this review. This article represents my personal opinion and is not influenced by, nor does it necessarily represent the opinion of my employer, or of MadCap Software.

I’m still working on a post to give you the details to help you decide if you should upgrade your existing Flare project to V6 (which I’ve been previewing for about a month), but alas, with work deadlines that post will have to wait until tonight.

So check back tomorrow for my Flare V6 review and upgrade guide!

• Dramatically faster build time for PDF targets
• Smaller file sizes for PDF targets
• Auto Save

Dramatically faster build time for PDF targets

The first thing I noticed when I built a PDF target using Flare 4.2 was how fast it was.  I’ve commented in the past about how important hardware is in getting the best build time from a Flare project, but I’ve become accustomed to the build time for my hardware set. Last week in Flare 4.1 I build three PDF targets, then I re-built them in 4.2.  Here is a break down:

So, a group of targets that were taking me a total time of more than 20 minutes to build now build in less than 5 minutes. That is a significant improvement.

Smaller file sizes for PDF targets

The next thing I noticed when I built a PDF target was how the file sizes are dramatically smaller now. This is another place that 4.2 shows huge strides. Check out these file size comparisons between 4.1 outputs and 4.2 outputs from my current project:

There are going to be a lot of happy customers when they see this! My three PDFs used to exceed 50 MB in size (added to our project’s already large download file). Now these same files only take up less than 10 MB in size. Wow.

Auto Save

MadCap has finally introduced a feature that is sure to please long time Flare users: Auto Save. You can set Auto Save in the Tools | Options setting. When enabled, by default, Flare will auto save your topics every 10 minutes. I set mine to five. Back when I was using Flare 3, this would have been huge, huge, huge, because I had serious stability problems with Flare (due to some problems with my computer, it crashed at least once per day). I now have a different system, and combined with my Flare 4 upgrade, I’ve had a serious improvement in application stability. I don’t think Flare crashed even once on me during all of January.

Auto Save is a fantastic improvement, but I’m even more thrilled with the overall stability of Flare, which seems to be much better in the V4 line than it was in the V3 line. But if you’re stuck with some kind of problem like I had on my old machine where some conflict causes Flare to be unstable for you, then you’ll really get bang for your buck for this feature. (Especially since it is a free upgrade for all Flare V4 users.)

Conclusion

I am thrilled with this release of Flare. The improvements for my projects are significant, and I’m not even a Feedback customer. If you are a Flare 4 user, upgrade today. If you aren’t a Flare 4 user, what are you waiting for? Join us in the 21st century. You’ll be glad you did!

—–

Disclaimer: If you aren’t aware, I’m a Flare Certified Trainer, and have been certified MAD (MadCap Advanced Developer). I’m also a MadCap MVP  (volunteer administrator) in the MadCap forums. I’m an avid Flare user and advocate, but not a MadCap employee.

Several times every week, I will be working on documentation, and I’ll use a feature in Flare (for example, conditional snippets), and I stop and literally say, “Wow. I love Flare.”

Now, you might expect a MadCap MVP (i.e. volunteer forum moderator) and a MadSkills Certified Trainer (which isn’t my day job) to like the company that produces the software. I’ll admit I have a bias. But I became a MVP because I loved the software enough to contribute to the MadCap forums regularly. Then I was invited to join the MVP group. And I didn’t set out to be a Trainer. MadCap actually contacted me, because they know how much I know about and like Flare, to see if I could pick up a training session that the other trainers were unavailable to take.

In any case, when I see a blog entry like this, I have to be even more grateful for the fantastic people in MadCap’s support department. In the post, MK Anderson talks about an unresolved customer service incident with Adobe that has been going on since August (4+ months!). And we’re not talking a complex custom feature request. We’re talking about getting a valid product key, even for a newly upgraded product.

I compare that to the customer service I’ve personally received from MadCap software, and the comparison is stunning. I have bronze-level support from MadCap. Yet, several times, MadCap has CALLED ME on the phone to better understand a technical problem I’ve reported. All my support requests have been resolved within a few days (though some of the resolutions were “we’ve filed a bug” — which is all you an say for some issues). MadCap Support doesn’t give up on difficult to find issues; once there was a bug being reported by a couple of customers, but MadCap couldn’t track it down. They worked with the few customers reporting the issue until we discovered repeatable steps to encounter the issue, then they fixed it that same day. Try getting that kind of support from Adobe.

So here is a shout out to all the fabulous people at MadCap Support. Thanks guys for a job well done! You are a big, big part of what makes using MadCap software a great experience.

We’ve discussed before how the best way to do this is to use a snippet, which essentially is a really long, formatted variable.

To do this in Flare, you create a new snippet, then you locate the text you want to re-use, and copy the text out of that topic and paste it into the snippet. Then you replace the text in the original topic with the snippet, then insert the snippet into the new location.

This isn’t too hard, but I’ve long wanted to use a nifty shortcut, but couldn’t figure out how to make it work. See, when you are writing in the XML editor, there is an option on the context menu (right-click) menu that allows you to create a snippet from an existing block. That works great if all you want to add to the snippet is a single paragraph, but it doesn’t work if you want to add multiple block-level elements into the snippet.

Today I thought of a way to do this quickly and easily, even with multiple blocks.

Here is what you do.

1. Open the topic that contains the text that you want to turn into a snippet.
2. Select the blocks that you want to re-use.
3. From the Format menu, select Group.
4. From the pop-up, select the div option. (This groups the selected content into a single block, the DIV block.)
5. Now, right click on the DIV block, and select “Create Snippet”.
6. Give the snippet a name and click the Create button. The snippet is created and inserted into the original topic
7. Go to your new topic and insert the snippet into it.

If you are creating Word or Framemaker output, you may need to change one additional thing:

1. Right click on the snippet block, and select “Open Link”. The snippet file itself opens.
2. Right click on the div block, and from the Edit menu, select “Unbind”.

This removes the div, which can cause positioning problems in Word and Framemaker outputs. (I don’t actually know if you NEED to do this extra step, but it isn’t a bad idea.)

Using a div to create a snippet is much faster, in my opinion, when you are trying to create a snippet from a multi-block selection. Try it, and I think you’ll agree.

—–

(This article has been cross-posted on DocGuy Training.)

If you’ve been following my blog recently, you’re already aware that I’ve received MadCap Certified Instructor status from MadSkills, the MadCap-owned company that provides training on MadCap products. I created a company for my consulting and writing work (I’m currently in the process of writing several books on Flare). Thus, I’m pleased to announce my company’s new website, docguytraining.com.

DocGuy Training’s website will give you tips and tricks on using MadCap products, as well as info on  my upcoming MadCap books. It is where I will discuss training events and other help-authoring tool information.

When you go to the website, you’ll see several different sections. The website is powered by wordpress, and each of the different sections show the most recent post(s) in a specific category. The bottom of the site has a link to the site’s feed; when you subscribe to the feed, you subscribe to posts from all categories, so you’ll be caught up on the latest information, if that is the route you want to go.

Don’t worry that I’m abandoning this site. I’ll still use Technically Speaking to cover lots of general technical writing information, and I’ll occasionally cross post informaiton on both sites.

Come check out my new digs at docguytraining.com and let me know what you think!

Hi Paul,

I hope all is well.

As a current Flare user, I thought you would be interested in learning that we have just released Flare v4.0 and Blaze v1.0! Blaze is our new print-only solution, while Flare remains the premier tool for printed document and web help authoring. I encourage you to download the new trials and give them a spin: http://www.madcapsoftware.com/downloads/

In addition, please visit this site for a blog article with great insight on Flare 4 you may enjoy: http://blog.paulpehrson.com/2008/09/02/madcap-flare-4-preview/

Finally, and the last link I swear – a newly recorded demo by V.P. Mike Hamilton about the new features in Flare V4: : http://www.madcapsoftware.com/training/demos/flareV4Signup.aspx

[...]

Let me know if you would like additional details or if there is anything that comes up that I can assist with. I look forward to hearing from you.

Best regards,
[MadCap Representative]

Pretty cool, eh?

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

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

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

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

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

Thanks for your help.

Good Luck!