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.

Mozy has been great. It runs in the background and every so often updates the online storage with the latest files from my laptop. At under $5.00 a month, this is a solution that works nicely for me. I suppose, it is $5.00 of insurance because hopefully you’ll never need it, but it is $5.00 for peace of mind.

Like I said, I never expected I’d need it. Until last night. My computer had a catastrophic failure. I have no idea what happened. I hadn’t installed any new software or drivers or hardware for a couple of weeks (at least), but yesterday it failed to restore from hibernate. We ran several tests and it wasn’t able to fix itself.

Now, normally, I’d be panicking right now. This is the main computer in my house. It has all my writing for the book I’m working on. It has all the web work I’ve done including my backup files for my website. It has all my photographs and my music. I had over 60GB of data that was gone in an instant. But I’m not panicking, nor am I inhalint anti-anxiety meds. You see, I’ve got Mozy. And they’ve got my back.

Mozy is a great service. You download the Mozy client, and you tell it what directories you want to back-up. One folder I backed up was my “Users” folder in Windows, because that contains all my critical data.

Mozy gives you 2GB of backup free. If you want unlimited backup, it’s $4.99 per month (with discounts if you purchase larger blocks of time up-front). If you want to add a folder to the backup repository, but it isn’t already there, you can just right-click on the folder in Windows, and say “Add to Backup”.

When something goes wrong, you can either restore a specific file, an entire directory (including sub-directories), or in the case of a catastrophic loss you can request backup downloads, which get compiled in 3GB increments and which you can download from Mozy’s website. These backups are executable files that you can run to restore all your old files in their former locations. All of that is free (well, included in your monthly fee if you have more than 2GB of data).

If that solution doesn’t work for you, Mozy can even take your entire backup, burn it to DVD, and mail it to you. That is not a free option, but it is probalby the easiest option, and it is the option I chose for my data restoration. When I tried to restore my backup files, I was able to download several of the backups, but not all. I have high-speed internet (which, by the way, is required to use Mozy), but I think my ISP may have been throttling my speed after I tried downloading 15 GB + of data in a couple of hours. I didn’t have the paitence to keep waiting, so I decided that to restore all 60BG+ of my data, I’d request the DVD restore option.

Honestly, this option cost a lot more than I expected. They charge a base fee of $30 for setup, plus $.50 per GB for the media, plus $40 for shipping (Next Day Air, shipped via FedEx). So my restore of 60GB was just over $100.00. I understand the setup and media fees. I was dissappointed that the only shipping option was FedEx Next Day Air. There are many shipping options, and I wish Mozy had let me pick my price depending on how urgent my need was.

Now I await my restore DVDs. I am very happy that I selected Mozy’s service. Even though it cost me $100 to get my data back (because I dind’t want the free download), that is still a lot cheaper than what I would have paid to recover the files from my hard drive. And my music and images are worth the $100.00 restoration, because really, the photos are priceless.

If you don’t have a backup solution in place for your computer, I recommend you consider a solution like Mozy. It saved the day for me this week. When will it be your turn?

(By the way, I’ll write a new post after I’ve been able to restore my data, so I can tell you how easy/hard it was. Stay tuned!)

I complained last week about Jing’s latest release, and how when I capture small videos and play the SWF file directly, the video scales to the browser viewport size. So videos that I had captured at 300×200 pixels were being displayed six times their size in my web browser, and like 10 times their size on my boss’s monitor.

I’ve had an extended conversation with TechSmith’s support department over this issue, and then yesterday I received an e-mail from a developer who is working to resolve the problem.

We’ve now written back and forth a couple of times, discussing ideas to resolve the problem.

I’ll wait until the next release of Jing to decide what I think about this whole issue, but I wanted you to know that what I think TechSmith is getting right, so far, is  how they are handling my complaint. I feel like my concern has been not only heard, but is being acted upon.

In the end, TechSmith will have to make a decision on how to proceed based on what they think is best. But at least I know that my voice has been heard and considered.

Thanks, TechSmith.

I’ve been looking forward to the latest version of Jing, which was released last week, and when it first came out I found some things that I loved about it.

Unfortunately, however, I have decided that TechSmith blew it big time in one critical area for me.

To understand why this is important, let me give you a bit of background.

Like I said, Jing lets you take a quick screen shot or video of your comptuer desktop. This tool has become a valuable tool in my kit. When I’m working with pre-release versions of my company’s software, I often discover bugs. I can quickly take a screen shot of a problem in our application. Jing saves the screenshot to a pre-determined location, and puts the filepath on my clipboard. I go to the bug repoting system, and just click “paste” to put that filepath into the attachments field. It makes attaching an image to a bug report VERY quick, and painless.

The same thing goes for screen casts. When I find a bug that results from a process I encounter, or whose functionality is better shown in a video, rather than captured in a still image, I can use Jing to grab a video, record my audio commentary of the bug. When I save the Jing video, Jing saves the video to a pre-determined location, and puts the filepath on my clipboard. I go to the bug reporting system, and paste the filepath into the attachments field. My developers love it.

I also send jing videos and images via instant message to my co-workers all over. It is a quick and easy way to share information.

However, the newest Jing, released last week made a major change to the way that videos are shown when you play them. Now videos expand to the full window size, regardless of the size of the recording window. I never record full-page videos. It is harder for people to process, and wastes space on the file system. Now, when people open my videos by opening the video from the bug system, or by clicking on the link in my IM, the video plays full screen. My boss has a 30″ screen. I created a video that was about 300 pixels wide by about 200 pixels high. It was expanded to full screen on his monitor. He had to stand back several feet to even understand what he was seeing.

I contacted TechSmith to disucss this issue. They tell me that this is a “feature” in the new version of Jing, and suggest that I embed the video into an HTML page to control the video size.

Nonsense. This is about quick sharing. There is no way that I’m going to take a video, then create a html page, then embed the image into the html page, then save the page, then upload the page to a server and then send the html page’s location to a co-worker. Not going to happen. Remember TechSmith? This is about quick sharing of information. There’s nothing quick about making me embed the video into an html page in order to make the size be at  100%  of the recorded size.

I wish I were writing about what I like in the new Jing. Problem is, I can’t recommend it for anybody who wants to take video  because I believe this “feature” makes it unprofessional at best, and unusable at worst.

TechSmith? Can you hear me? Can you fix this please?!

—

Update (1/29/09): TechSmith heard and answered. Check it out.

I’ve got somebody like that in my list.

In the last hour, I’ve received 31 tweets. Of those, 24 have come from a single person.

Wait, just got another. 25 tweets in a single hour. Shut up already! Or, if you have that much to say, get a blog!

I’m tempted to de-list the noisy one, but he is well known in my industry, and I do find some of the tweets interesting. I just think that this is getting old fast.

How do you do it? I mean, how do you handle the tweeter who won’t shut up? Do you de-list? Are you ever the noisy one? Do you think before you tweet? Or do you think that you shouldn’t have to?

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.

My twitter page is: http://twitter.com/docguy

You can see my “tweets” in the sidebar (under “What I’m doing…”)

11. Content license from you

11.1 You retain copyright and any other rights you already hold in Content which you submit, post or display on or through, the Services.

So, I guess there is less to worry about now.

Has Google gone off its rocker with Chrome? Does Google’s Motto “Do No Evil” not mean the same thing to them as it does to me?

Yesterday I downloaded Google’s new browser, Chrome, and I’m heading back to Firefox. (I won’t pass GO, and I won’t collect $200.) The browser is nice and clean, but it has its problems: (1) for some reason, I can’t add Facebook friends using Chrome. I have to open the page in Firefox to do that. (2) Chrome won’t display the web application we develop at work (AJAX [thus JavaScript] based, which is supposed to be a STRENGTH of Chrome). Oh and (3) Chrome users give Google a license to do WHATEVER THEY WANT with any content that we view or upload using the browser.

“By submitting, posting or displaying the content you give Google a perpetual, irrevocable, worldwide, royalty-free, and non-exclusive license to reproduce, adapt, modify, translate, publish, publicly perform, publicly display and distribute any Content which you submit, post or display on or through, the Services. “

(I first read about this story here, on Gizmodo.com.)

Let’s consider the implications of that:

• Any content I submit to my blog using Chrome gives Google a perpetual, irrevocable license to publish, publicly display, or distribute any way they want.
• And e-mails I sent using Chrome gives Google the same license to share my private information with anybody they want however they want.
• When I access my banking information, Google has the right to reproduce my balance and transaction information, and publish that information publicly.
• I help people build websites on the side. Any content I create for my clients and upload or view through Chrome gives Google the right to modify, reproduce, adapt, and publish wherever and however they want.
• I work for a company that produces Web-based software. If I view our proprietary information with Chrome, Google has the right to harness that information and use it wherever or however they want.
• If my employer uses Chrome to administer confidential employee data, Google can intercept, store, publish, store, and broadcast that information.

11. Content license from you

11.1 You retain copyright and any other rights you already hold in Content which you submit, post or display on or through, the Services. By submitting, posting or displaying the content you give Google a perpetual, irrevocable, worldwide, royalty-free, and non-exclusive license to reproduce, adapt, modify, translate, publish, publicly perform, publicly display and distribute any Content which you submit, post or display on or through, the Services. This license is for the sole purpose of enabling Google to display, distribute and promote the Services and may be revoked for certain Services as defined in the Additional Terms of those Services.

11.2 You agree that this license includes a right for Google to make such Content available to other companies, organizations or individuals with whom Google has relationships for the provision of syndicated services, and to use such Content in connection with the provision of those services.

11.3 You understand that Google, in performing the required technical steps to provide the Services to our users, may (a) transmit or distribute your Content over various public networks and in various media; and (b) make such changes to your Content as are necessary to conform and adapt that Content to the technical requirements of connecting networks, devices, services or media. You agree that this license shall permit Google to take these actions.

11.4 You confirm and warrant to Google that you have all the rights, power and authority necessary to grant the above license.

So their license allows them to do it in order to “display, distribute, or promote the Service.” That’s pretty vague, and I imagine it could be argued that a lot of what Google does falls into that category.

Um, thanks, but NO THANKS.

Off to uninstall Chrome until this has been resolved.