Hi Paul…

I stumbled upon your blog while googling MadCap Flare. I just started a new job and I’m the first tech writer. I have the ability to pick my application. I’m a Frame user from way back and recently went through the cumbersome process of single-sourcing using individual FM files and conditional text. What a logistical nightmare. I can do this with no problems but it sounds like MCF might be the wave of the future. Long story short… at the new company, they have a SW release every 6 to 8 weeks so I need to be quick with updating the documentation. Of course, single sourcing came to mind but I broke out into a cold sweat remembering the FM hoops I had to jump through in my previous life. I can tell you L-O-V-E MCF. What type of single sourcing projects have you done using MCF? Any input or advice you have would be most appreciated. And feel free to ask me questions. Thanks so much.

Desma

Here is a slightly edited version of my reply:

Desma,

Thanks for contacting me.

Yes, I do love Flare. It is an awesome tool and has a great community. I’ve had great support from within MadCap, and I am an avid fan of the MadCap user forums.

Before I begin, it is probably fair to share my bias. I’m a certified Flare trainer.  Additionally, I’m certified as a MadCap Advanced Developer. Finally, I’m an MVP in the MadCap Forums (which means I’m a volunteer forum moderator).  So, I have a strong bias towards MadCap. Not only do I love their tool, but people pay me money to teach them how to use (and hopefully come to love) it.

That said, training for MadCap is a side job for me. My day job is as a lone technical writer for a software company. I provide user guides, release notes, installation guides, administration guides, and on-line help documentation for four separate, but related products. I use Flare every day as my primary authoring tool. I capture screen shots using MadCap Capture and use Capture to single source my images for online and printed outputs. From the same source files, I create direct-to-PDF printed guides and context-sensitive online help. My computer is set up so that every night, Flare automatically does a build of my project, and copies it out to the network where it gets picked up by our nightly build script; that way, every time our software builds, it is getting the most recent help I’ve written, both in PDF form and in WebHelp form.

I use condition settings all over my project to keep content separate and ensure only the proper topics occur in the proper output. All my content for all four projects lives in the same group of source folders. I use TOCs, targets, and conditions to get just the topics I need in the order I want them for each of my output types. And like I said before, each of these projects builds every night, by itself.

I’m creating high-quality PDF output, which looks really nice using custom page layouts with full-color, full-bleed headers and footers. I have one group of settings for my online output (font face, font size, color scheme), and a seperate group of settings for my online help (font face, size and color, etc.) But these all come from the same source files. I set them up once in the style sheet and then the rest just happens automagically when the project is built.

As a lone writer, I’ve found that Flare is a great product for meeting my company’s documentation needs. Last week, my boss asked me to create a new manual, using existing content. I had a PDF with a cover, table of contents, content, glossary, and index ready in PDF format in 10 minutes. He jokingly told me, “It’s that easy? We’re paying you too much.”

I’ll be honest, Flare has quite a learning curve. If you’ve used a help authoring tool (like RoboHelp or WebWorks, or AuthorIT, etc.) in the past, then you will have a smaller learning curve. I hadn’t used a HAT for several years (and even then, had only used one for a couple of months.) It took me a while to figure out WHAT Flare was doing, and how to make it do what I wanted. I didn’t make the investment in training when I first started, and I think that made my ramp-up time a bit longer than if I had just jumped in and did training when I started.  (Obviously, this is a conflict of interest in my advice, though, because I provide training for MadCap products. However, even if you don’t want ME to do your training, I think getting some training is valuable.)

If you intend to use Flare, I’d be clear to your supervisors that you may need up to 2 months ramp-up time before you are ready to produce a customer-ready output. I’d also recommend that you get a maintenance agreement from MadCap. It is the best money my TechPubs department spends each year. We have the bronze agreement, so we have unlimited e-mail support from MadCap, plus we get the next version of Flare that is released (one new version is released each year) for free.

If you haven’t done so yet, download the trial version from MadCap’s website and take it for a spin. There are some great manuals that you can print out from the Flare help system, or you can use the individual topics in the Flare help system to get you started. I’d also consider attending some of MadCap’s FREE webinars. They have tool-specific ones, as well as general webinars that you can use to become acquainted with things like topic-based authoring and CSS.

Product Demos are listed here: http://madcapsoftware.com/demos/product.aspx
Webinars are listed here: http://madcapsoftware.com/demos/webinars.aspx
Support demos are listed here: http://madcapsoftware.com/demos/support.aspx

My other piece of advice is this: if you decide to purchase, be sure to talk to a sales rep. You can often get something thrown in for free or for a discount.  Your sales rep might be able to work a deal for you.

I am very pleased that I switched to Flare. I had been working in this company for about six months before I realized that Frame wasn’t going to meet our needs going forward. I had heard about Flare, and knew people who were using it, so I decided to give it a shot. I started with very little background knowledge, but worked on it and used the forums, and over the next several years have become not only an expert, but an advocate as well.

I hope this helps to answer your question. Please feel free to follow up with other questions, thoughts, or anything that you feel needs clarification.

-Paul Pehrson
www.DocGuyTraining.com

PS: Of course, if you decide you want training, I’d be happy to talk to you about training options <grin>

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.

From MadCap’s site:

The certified MadCap Advanced Developer (MAD) program recognizes and validates your ability to use MadCap products. Being certified MAD for Flare™ is the best way to demonstrate your abilities and to stay up to date with MadCap Flare.

So there you have it. I’m officially, certifiably, MAD. And pretty happy about it.

To acquire this update, go to the Flare 4.x download link that you recieved by e-mail (search your e-mail for a message from MadCap with the subject “MadCap Software Order”).

If you have already upgraded to 4.1, you will need to uninstall 4.1 using Add/Remove Programs, then you can install the updated 4.1. If you are running 4.0, you can just double-click on the download, and 4.0 will be uninstalled as part of the updated 4.1 installation process.

If you are nervous and want to wait out the upgrade for a couple of weeks, well, I don’t blame you. I’m in the process of upgrading right now (but this dinosaur of a computer takes about an hour to install Flare, so I’m blogging during the process).

Stay tuned here to find out the newest information on how the 4.1 upgrade goes. I’ll let you know if other users are reporting problems.

Forum users are reporting that they get unhandled exception errors when they open projects, but even more alarmingly, they report that text that is added to a <span> disappears from the editor and all output. Most of these users report rolling back to 4.0, so again, if you haven’t made the switch, you may want to wait until some of these early issues are resolved.

Let’s just hope that MadCap issues a different version number for the release, so Support will be able to tell which version users have installed. I remember an update a while back where MadCap updated a recent release, but didn’t change the version number, so it was hard to know which version customers were using.

And lets hope for a quick fix. I believe MadCap will be able to do it. They respond better than any company I’ve ever worked with. They’ll get this under control, and you can benefit from the newest Flare enhancements very soon.

EDIT (12/4/08): For what it is worth, I can’t duplicate either problem in my instance of V4.1, so I’m leaving 4.1 installed. Proceed at your own risk. If you’ve got a project due in the next couple of days, you might want to wait. If you aren’t under a pressing deadline, install it and see if it works for you. The problems reported certainly aren’t universal, so they may (or may not) apply to you.

I can’t find release notes posted to the MadCap Knowledge base yet, but the Flare update prompt lists the following new features:

New in this version:

• Improved XML Editor performance
• Improved Handling of tables in all printed outputs
• Improved FrameMaker and Word import
• Improved functionality of cross references in all outputs
• Improvements for native PDF and XPS outputs
• Fixes for bugs found by users
• And many other functionality enhancements

The announcement also states that new dot versions are available for X-Edit and Analyzer. You can update them using the same method for updating Flare.

My own upgrade from V4 to V4.1 took my computer about an hour to complete, however this is a fairly slow computer. I’ll be interested to see how my new Vista laptop does for the installation. I also had to upgrade Microsoft SQL Server Compact edition to version 3.5 SP1 when I launched Flare, but that was pretty painless. With both updates, my upgrade took slightly more than an hour to complete.

You can read about this announcement in the MadCap forums, in a post from Rick Ferrell (MadCap Support).

MadCap Capture V3 solves part of that problem. See, Capture V3 is integrated with MadCap Ling 1.5, so when you use text callouts in Capture, then you package up your project to translate in Lingo, you will also be packaging in the Capture callouts.

Your translator using Lingo will then see those callouts when they are translating the project. The resulting localized project will include the translated image callouts, which are included on your images when you build the localized version of your project.

That is cool functionality.

—

Edit: Mad props go to MadCap Support guru Rick Ferrell for his help answering this quesiton for me today on the fly. Thanks Rick!

On wednesday evening, I’m presenting a session entitled “DITA and MadCap, what’s the scoop” and on Thursday I’m doing a presentation moving from FrameMaker to Flare (which not coincidentally is the topic of the book I’m currently writing.

I’m excited to be here and talk to people about DITA and the tools that MadCap is creating to help DITA authors do more faster.

But we’ll get there in good time. Now I get to just sit back, relax, and listen. And Twitter and blog occasionally.

—-

I probably should point out again that I’m not an employee of MadCap Software, though I am a Certified Flare Instructor, and do have a consulting contract with MadCap. (That adventure is to come next week; I leave on Thursday from the conference and fly to the Middle East.)

I find that when I create an an output, I find an error, then I go back into Flare and fix the error I found, then I rebuild my project, and then start the process over.

You don’t have to do it that way. Instead, you can use a feature in the WebHelp output to identify all the topics that have problems and then go back and fix them all at once. The feature I’m talking about is the Favorite Topic feature.

On your WebHelp toolbar (unless you disabled it in your Skin Editor) there is a star icon. When you click that icon, the topic you’re viewing is flagged as a “favorite.” You can then open the Favorites accordian tab to view all the topics that have been fav-ed.

When I’m proofing my WebHelp output, I’ve found that it is much faster to flag topics that need corrections with the “Favorite” flag. I can then continue on to the rest of the topics. Once I’ve been through everything, I can go to the Favorites accordian tab and see the topics that need my attention.

That is one proofing hint that works well for me. What proofing tips do you have to share? Tell us what proofing tricks YOU use when editing your work in the comments below.