With that in mind, and as an opportunity to give more visibility to my sponsors, I offer a regular “Message from the Sponsors” post. I give each sponsor the opportunity to let my readers know about their products and services. I hope you can think of this post as similar to strolling down a virtual conference exhibit hall (at least a little bit).

Clarify: Image capture, Image editing and Document Authoring – Together at Last

So many of us have suffered through the tedious process of capturing screenshots and posting them into Word or some other text editor. When you’re trying to communicate quickly, this can be like flying down the highway only to get stuck in the worst Los Angeles traffic imaginable.

Clarify removes the traffic jam. With fast and flexible screen capture tools, you can quickly grab multiple images. As you capture the images, Clarify creates a document for you. Everything you need to author your document is right there, including text entry and image annotation tools, such as arrows, boxes, blur, highlight, borders, image resizing, and cropping.

Clarify is great for banging out a quick how-to, providing fast revision notes to a colleague, or for providing application feedback for developers. And at just $29.99, it’s extremely affordable. Clarify is available for both Windows and Mac.

Download a free 14-day trial and see how much more productive you can be when working with an integrated screen capture, image-editing, and document-authoring tool.

Learn about content strategy in technical communication with Scriptorium at LavaCon

Ryan Fulcher, Alan Pringle, and Sarah O’Keefe will be attending LavaCon next week with free chocolate (of course!). Stop by our booth and don’t miss Sarah’s session on content strategy in technical communication. We look forward to seeing you there, or on our next round of webcasts! (Note: After our move, our direct phone numbers changed. Please contact us via 919-481-2701 or 866-605-9677.) For more information about Scriptorium, see http://www.scriptorium.com.

Controlled English with Congree – the New Standard in Technical Writing

Congree is the world’s premier controlled-English authoring assistance software. Working as a plugin to a variety of editing tools, including JustSystems XMetaL, Congree helps you leverage on sentences you and your team have already written, unify your abbreviations, terminology, and acronym usage, and ensure that everything you write conforms to your corporate style guide. Congree functions as a simple plugin, and is both customizable and extremely easy to use. Get the most out of your XML authoring with Congree. Please join our joint webinar with JustSystems on Wednesday, December 7, 2011 by following this link.

Dr.Explain 4.5 released

A new version of likely the most eccentric help file authoring tool, Dr.Explain, has been recently released. A free demo copy of Dr.Explain 4.5 is available at http://www.drexplain.com/download.

Unique to Dr.Explain is its innovative approach to creating help documentation much quicker than with other tools. The program parses a live application and automatically produces screenshots of its windows along with a sequence of explanatory callouts for each control.

Dr.Explain 4.5 update includes about 200 improvements, features, and optimizations in total.

Annotation Template Editor is one of the coolest new features of the new release. It allows to create callouts of any design, complexity & style. Now you can prepare amazing annotated screenshots and graphics and insert it into your help documentation in a single tool.

For more info about the Dr.Explain help file and on-line manual authoring tool, see http://www.drexplain.com.

Tedopres International – www.tedopres.com

Also known as Simplified English, the main objective of a controlled language is to make technical text easy to understand. Tedopres HyperSTE standardizes vocabulary and style according to linguistic style guides and standards like Simplified Technical English, aiming to improve consistency, eliminate ambiguity and reduce complexity. It also provides objective criteria for quality control. Controlled Language includes a general dictionary and a set of writing rules. In addition to the general vocabulary, companies can define their own Technical Names (terminology).

A few benefits of controlled authoring include:

• Quality assurance and improvement
• Standardized way of writing
• Improved safety
• Efficient authoring
• Reduced time to market
• Improved customer experience
• Facilitates XML, content management, structured authoring (Information Mapping,DITA, S1000D)
• Considerable cost savings
• Cheaper, faster and better translations

For more information, see www.simplifiedenglish.net.

You can also learn about controlled authoring with Tedopres’ HyperSTE at LavaCon. Join Tedopres at LavaCon, November 13–16, 2011, Austin, TX, where Berry Braster (Sales & Marketing Director and implementation expert) will be speaking in a panel discussion titled, “Controlled Language – Making it work for you!” The panel discussion will include Kit Brown-Hoekstra of Comgenesis (she will moderate the panel), Sherri Sotnick of Elekta (who implemented Elekta Approved Simplified English), Berry Braster of Tedopres (implementation expert) and Poppy Quintal (standard expert). For more information on Lavacon, please visit http://lavacon.org. Please contact us to be eligible for discount coupons. For more information, please contact us at ste@tedopres.com.

To learn more about TedoPres, see www.tedopres.com

Adobe Celebrates the 20th Anniversary of RoboHelp with a Limited Period 40% Off “Switcher” Promotion

Struggling with your current help authoring tool? Looking to “switch” to a tried-and-tested tool, one that has been the professional standard in the user assistance space for the last 20 years? Adobe has the answer … and the perfect reasons too!

Adobe celebrates the 20th anniversary of RoboHelp with a limited period 40% off “switcher” promotion. Switch from MadCap Flare, Author-it, or Doc-To-Help Enterprise or Doc-To-Help for Word and save 40% off Adobe RoboHelp 9!

Time frame: October 17th 2011 through February 16th 2012
Scope: US only

For more details (top reasons to switch, testimonials, switching resources) about the RoboHelp 40% off “switcher” promotion, please visit http://www.adobe.com/products/robohelp/switch.html

To learn more, please sign up for the upcoming Adobe RoboHelp “Switcher” webinar at 10.00 am PST on 30th November (Wednesday).

Information Design online grad programs at Southern Polytechnic

Life is full of choices. So why choose Southern Polytechnic’s online graduate programs in technical communication and information design and communication?

Because we’ve been in the “business” of teaching online for years, so we have the hard stuff down, and our MS degree has been around since 1988–yikes!  Almost before the Internet (well, not quite).  Nowadays, we have an online graduate certificate in tech communication, four advanced certificates, and the full MS in Information Design and Communication, all online.

We’ve got great grad faculty who practice what we teach, who engage with you in a combination of weekly discussions (asynchronous so you can communicate even in your bunny slippers, if that’s what works best for you), and weekly projects that grow to bigger projects, both individual and team-based.  The result: you learn by doing, by sharing, and by producing and you build a great portfolio of your products to take to market.

For more about our programs, visit us at idc.spsu.edu.

New Release: MadCap Mimic 6

MadCap Software is pleased to announce the release of Mimic 6, for software simulations and tutorials.

New features in Mimic 6 include:

• Audio Narration
• Audio Objects
• Improved Recording Workflow
• Flash Embedded Skin Enhancements
• Flare 7 Integration
• And Much More

Watch the What’s New video here:
http://www.madcapsoftware.com/products/mimic/overview.aspx#whatsnew

To learn more about Mimic, visit:
http://www.madcapsoftware.com/products/mimic/

Upcoming Webinar:  Strategies for Building and Managing Large Online Libraries – Nov. 30, 10am (Pacific)

In this webinar, learn some key methodologies for starting a large project, gaining client/employer consensus, and making your way from ground zero to useable, accessible procedures. These solid practices will help you regardless of the help authoring tool you have selected.

Presenter: Beth Gerber, Lightext, Inc.

Sign up: http://madcap.us/sa0YK3

For more information on upcoming webinars, and past webinar recordings, visit:
http://www.madcapsoftware.com/demos/webinars.aspx

Competitive Upgrade Pricing on MadCap Flare, MadPak

The reasons to switch to MadCap Flare from other tools such as RoboHelp® and FrameMaker® are growing.

As the original creators of RoboHelp®, the team at MadCap Software developed Flare from the ground up, using the latest technologies, with the vision to create the most advanced single-source, multi-channel publishing application on the market. Now in its 7th release, Flare boasts an impressive list of features and functionality.

Flare was the first to introduce features such as native mobile output, and to launch a complete suite of fully integrated tools to support the entire authoring, contribution, review and localization process.

Users switching from other legacy tools can save up to 50%.

For more information about switching to Flare, including case studies, white papers and transition guides, visit:
http://madcap.us/uKEjBT

—————————–

If you’re interested in getting your message out to technical communicators, let me know.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

The main issue for me is between authoring static in-house documents using single-sourcing methods before publishing, or capturing information sources dynamically after publishing from online social networks, linked data sources, and knowledge mashups.

The myth of single-source authoring is that it actually has a life in the future and remains a viable goal for many information developers. With so many mega-trends against it—such as the belief that static authoring from a single vantage point from a single author paid by a single organization is a workable system—seems ludicrous. Instead, we should be looking to capture, sequence, and give context to the wealth of rich content already published in context from the Web. Collaborating with the many subject experts, authors, videographers, bloggers, tweeters, and writers coming together on the Web with shared interests will be powerful if it can be harnessed.

The myth of single sourcing

Michael undercuts the idea that you can create help from a single author working from a single perspective in a single point in the organization. To add to this scenario, usually that author is an outsider to both the environment and business processes he or she is documenting. Further, the author usually moves on to another project as soon as the software is released.

This morning I had a meeting downtown at SLC headquarters. I’ve become accustomed to wearing business casual clothes to work, but at headquarters, I have to wear a full suit because that’s the dress code. In an early morning meeting, I listened to several department leads explain my new project. It would involve extensive knowledge of cataloging and archiving techniques, a robust off-the-shelf system that had been customized, five main divisions or modules to conquer, each with their own resource leads, about 200 constantly rotating users complementing a core group of specialists, and an aggressive time frame.

As I listened and glanced through the archiving and cataloging procedures (did you know there’s a Society of American Archivists, and that they have in-depth protocols for how things should be done?), I realized that learning the business process surrounding the application would require complete immersion in each of the five divisions over the course of several months. I would need to constantly interview subject matter experts, participate in the actual archiving and cataloging processes, and make sure everything I created was reviewed, checked, and edited for accuracy by each of the five major subject matter experts. The end documentation would probably be several hundred pages for the initial release.

Keep in mind that I have about three other concurrent projects that I’m working on with approaching deadlines (unlike developers, no writer ever gets to work on just one project). Could I pull something together by February/March?

At this point, Michael’s post was resonating like a blinking banner in my head. Authoring from a single vantage point from a single author is … ludicrous.

Even if I were to import existing documents and materials from SMEs into a HAT, who would own it after I finished? Would I become a permanent installation in the department, constantly processing updates, verifying instructional clarity, addressing gaps and making edits? If not, would the documentation become stale six months after release, when SMEs decided to change their business processes?

In an organization where several thousand people have only a handful of actual technical writers, we’re a scarce resource. I bounce from project to project, like a little visiting angel (or devil) who works a little documentation magic and then moves on.

Another group on my team is tackling an even larger project, one that involves complex financials. They’re using Flare. They started using X-Edit and entitled a handful of business writers to contribute content with it, but X-Edit proved either too buggy or unworkable. Now the business SMEs are passing Word documents to the guys with Flare, who are inputting the information into the HAT. After release, the idea is to have the business department own the documentation and continue making updates using Flare. It will be interesting to see if they actually do it.

In thinking about these robust software scenarios, where products require extensive knowledge of business processes, have elaborate interfaces with hundreds of possible tasks, and are run by dozens of specialists constantly refining their own business processes, is there any other platform besides a wiki that can actually work? What else can you use to enable 10 different authors to make simultaneous updates, to maintain the documentation after the release? How else can you infuse the documentation with the intricacies of a department’s business processes?

Using any of the standard authoring tools — Flare, RoboHelp, Author-It, Doc-to-Help — leaves you with the ridiculous model of a single author working from a single vantage point from a single organization trying to pull together an ocean of information. Because that model is untenable and unscalable, HATs will fade in favor of collaborative web-based authoring technologies.

Note: Stay tuned for more on this topic. I’m interviewing Michael for a podcast this weekend. It turns out he practically lives in my backyard.

WordPress note for Thanksgiving: Remember that I do WordPress consulting, including design, development, and implementation of WordPress sites. Thanksgiving is a perfect weekend to get your blog online. If you need my help, contact me. Even if it’s only a small site tweak, such as changing font sizes or integrating Share This buttons, I can help you out.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

• Flare: 40%
• Framemaker: 33%
• RoboHelp: 27%
• Author-it: 13%
• Dreamweaver: 13%
• HTML Help Workshop: 12%
• Madpak: 12%
• WebWorks ePublisher: 11%
• helpware FAR: 7%
• RoboHelp for Word: 7%
• Adobe Tech Comm Suite: 7%

I also recently published an informal survey in my blog’s sidebar. I didn’t intend for it to gather so many votes, but 987 people responded to the question about which authoring tool was right for them. They answered as follows:

• Flare: 46%
• RoboHelp: 18%
• Framemaker: 18%
• Author-It: 14%
• Word: 14%
• Other: 12%

In 2007, WritersUA also created a tools survey. They asked participants to rate their satisfaction with various tools, and from their ratings they calculated tool usage. The tool usage by the 606 respondents was as follows:

• Acrobat: 93%
• SnagIt: 57%
• RoboHelp: 56%
• Framemaker: 48%
• Paint Shop Pro: 44%
• Dreamweaver: 41%
• Photoshop: 40%
• Captivate: 31%
• HTML Help Workshop: 29%
• WebWorks Publisher: 27%
• Madcap Flare: 25%

What can we learn from these tool surveys? According to some, these surveys prove nothing. For example, John Daigle on the Yahoo HATT listserv writes:

Basically, the results [of these surveys] measure a self-sampled population. Whoever sees the announcement of the survey gets to decide whether they want to participate or not. There’s no control whatsoever. (In fact, in most of the surveys I mentioned, you could vote more than once!!!) Understand. I am not criticizing any of these surveys. Surveys are fun. I just don’t think folks should get hysterical and make of them more than they are. Even the use of the word “statistical” is a stretch. The thing I DON’T want to see is some crazy extrapolation from any of those 3 surveys that suggest the results have anything to do with MARKET SHARE.

John’s main criticism of the surveys is the lack of representative sampling of those who participated. Many share the same opinion.

However, creating a survey that has a representative sampling of technical communicators across the globe is not only extremely difficult, it’s next to impossible.

To find a representative sampling, you would need to somehow determine the whole, so you could tell if your sample represented it. According to Tom Gorski, STC’s Director of Communications and Marketing,

Neither STC nor the Bureau of Labor Statistics can determine with any accuracy what that number [of technical communication professions in the world] is. I’ve seen estimates in the neighborhood of a couple hundred thousand. Part of the problem, of course, is that Technical Communicator is not a widely recognized position or profession. We’re working on convincing the BLS to change their definition of technical writer to the broader term that is more fitting for today’s challenges, but that will take time.

In other words, no one knows how many technical communicators there are in the world. The problem is partly due to the slippery and widely variant names for the profession. Are editors, illustrators, information architects, usability analysts, instructional designers, web designers, managers, e-learning professionals, and others who don’t literally call themselves technical writers or technical communicators included in the representative sampling?

In short, because it’s impossible to know the whole, it’s also impossible to extract a representative sample of the whole. As such, any survey that attempts to gather a representative sampling of technical communicators is in trouble.

Beyond sampling errors, the survey questions themselves are prone to error. If you limit the possible answers to a finite set of choices, respondents may be forced into selections that don’t represent their true answers. On the other hand, if you leave every question open-ended, the results are difficult to sort through and interpret.

Another challenge with surveys is avoiding assumptions. The question, “Which help authoring tool is best for you?” is different from the question, “What help authoring tool(s) do you use on a regular basis?” Preference doesn’t require usage, and usage doesn’t require preference. Hence, we shouldn’t assume that the responses should be the same.

For example, I spent an entire year using RoboHelp at a company that required it, when I really wanted to try something else. A significant number of writers use the default tools their company purchases for them or requires them to use, or which they can afford. The writer’s usage of the tool doesn’t mean they prefer it. Conversely, I may lust after a certain help authoring tool and know that it’s right for my needs, but I may not have the money, infrastructure, or time to implement the tool. So my preference doesn’t imply usage. See how those two survey questions can look similar but yield different results?

Despite all the tricky errors inherent in surveys, I think tool surveys still provide value. The rates of error decrease as the number of respondents increases, because the sample grows larger (similar to how a poll of 10,000 random people is more valuable than a poll of 10 –- the sample grows closer to the whole). As long as you aren’t targeting a small group from one sector of society, you can begin to see general trends and rough estimates.

I wonder how people who demand more rigorous, unbiased survey sampling would interpret the value of informal usability tests. For practical reasons, usability analyses are often done with a small group of four to five people, with a usability expert observing the users for an hour or so as they use an application. Despite the user sampling errors and the lack of comprehensiveness about the tests, usability experts can gain about 80% of what they would normally obtain from a more comprehensive, expensive usability analysis involving eye-tracking devices, keystroke logging, and screen recording software.

In other words, surveys aren’t exact, but perhaps they can give us a rough idea of what we’re trying to measure.

With those disclaimers, here’s what I’m taking away from the tools surveys:

• The breadth of the tools demonstrates the difficulty of relying on a single tool — there are tons of tools out there that people are using. Still, five main authoring tools dominate: Flare, RoboHelp, AuthorIt, Framemaker, and Word.
• Madcap is not only a major competitor to RoboHelp, but it now seems to now have an edge on it.
• It seems that, despite all the hype in the tool market for it, few people are using DITA.
• Madcap seems to have a strong investment in the perceived value of tool use. Judging from their marketing campaigns surrounding the surveys, they must feel that surveys (and tool popularity) influence a writer’s decision to buy a particular tool.
• People can’t change their toolset overnight (due to legacy documentation, training, deadlines, and other variables), but they do seem to be gradually shifting in the direction of Flare.
• Because generating a printable PDF document is the most common help authoring deliverable (according to another question in the HAT Matrix survey), a help authoring tool that can produce this deliverable will probably be sought with greater demand.
• You can use a variety of tools to get the same job done.

Finally, there is one observation that no one can deny: tools surveys are inflammatory among both vendors and users. This is no doubt because the surveys are influential, despite their flaws.

Are we done with surveys for a time? I think a good majority of people, especially those entering the field, will still ask which help authoring tool is the best, which help authoring tool should they learn. Links to the three surveys would be a good starting point in a response.

A variety of tools

A few weeks ago I started experimenting with surveys in my sidebar, mostly informal, and mainly to try out different WordPress plugins. Little did I know my surveys would incite so much controversy.

The latest poll, “Which Authoring Tool Is Best for You?” has received nearly 600 votes from people around the world, and was discussed at length on the HATT listserv. In all this discussion, I’ve realized one thing: technical writers are passionate about the tools they use.

“Passionate” is probably too positive a term. More like fanatical or zealous – but really technical writers span the spectrum with attitudes here. Some are fanatical, others are heavily invested, a few are open-minded, others are confused, and some are downright nasty.

The war over tools isn’t unique to the field of tech comm. It’s human nature to cling to a brand and promote it as the best. Think Dodge versus Ford trucks, Harley versus Yamaha motorcycles, BYU versus the University of Utah (replace with your local college rivalries), the Yankees versus the Red Sox, Mac versus PC, iPhone versus BlackBerry, West Coast versus East Coast, Twitter versus Plurk. The war of brands is pervasive and probably dates back to cavemen promoting different types of clubs to maim their kill.

Even as I write this post, someone has just twittered, “Movable Type, the most powerful blog software out there, hit 4.2 today.” Is Movable Type really the most powerful? Or is it WordPress, or some other?

Replace the word “software” with any other product and you catch the spirit of the branding war. Ford, the most powerful truck out there. iPhone, the most powerful mobile device. The Yankees, the most powerful baseball team to ever ….

An Alternative Point of View

Although tools seem to play a significant role in technical authoring, some people disagree. Bill Swallow is “shaking [his] head at all the tools survey nonsense going on lately.” He feels tools should play a minimal role in any project, not foregrounding the more important aspects of content generation. Spending 20% of your time formatting, structuring, designing and styling your content with a tool is “a huge waste of time,” he says.

Instead, tools should play “a very little role in our day to day work (or should).” Writers should simply choose the right tool for the job — like a skilled mechanic selecting a wrench from a toolbox — and go to work writing instead of wrestling with the tool.

Perhaps if everyone could work like this, we wouldn’t so easily slip into Pharisee-Saducee-like tool discussions. But while this scenario is ideal, it’s hard to implement because not everyone has the technical prowess of a Bill Swallow to make a tool eat out of your hand. In setting up single sourcing scenarios, or structured authoring templates, the tools and process can be a monster you battle. (Of course, once you set everything up, it’s no longer such a monster.)

Best Practice Attitudes

My discussion about tools isn’t conclusive nor is it meant to be. So instead I give you three “best practice attitudes” to have towards tools.

1. Embrace Tool Learning

You’re a technical writer, right? This is what you do – learn confusing software applications that engineers create. Learning tools should be your strength, not your weakness.

To make life easier, try not to learn a tool all at once. It’s better to take small bites over a series of weeks rather than pull an all-nighter under pressure.

2. Recognize that the “Best Tool” Is Relative

Certain tools are right for certain situations, skillsets, and corporate contexts. What’s right for you may not be right for another.

For example, WordPress may be tremendously powerful, but many users can’t understand it, so Blogger might be more appropriate, even though it’s less powerful. Similarly, DITA may be the way to go if you have heavy reuse, but if you only have one manual and no reuse, it would be overkill. Camtasia is great if you’re creating screencast tutorials, but Captivate excels at interactivity. Framemaker is better at long documents, but Word is fine if the job’s shorter. Right is relative.

3. Expose Knowledge Gaps

The next time a “best tool” war flares up, ask each person if they’ve used the other tool, and if so, to what extent. When we admit the limits of our knowledge, we’re more apt to be humble and open-minded when it comes to tool comparisons.

Conclusion

In this post, I have not taken a position of tool agnosticism. I do think that some tools are better for certain jobs than others. But we can be a lot more level-headed and open-minded when it comes to discussions about tools.

————

photo from Flickr

Download MP3

In this podcast, I talk with Theresa Putkey, a writer/usability consultant in Vancouver, about the largest project of her career. She explains how she approached a project that had upwards of 2,500 help topics, many of which consisted of duplicate content. She explains how she transitioned from RoboHelp to Flare, the advantages she found as well as her regrets, and how she configured the search to make it easy for users to find information.

Theresa recently presented a similar topic at Content Convergence and Integration, a conference in Vancouver. Her presentation was titled “SuperWoman, WonderWoman, UnderDog, and Leprechaun, with Flare: A case study in breaking down silos.” You can view the slides from her presentation on SlideShare.

Learn more about Theresa by reading her blog. You can also read Theresa’s articles on Boxes and Arrows.

Topics Covered in the Podcast

Topics covered in this podcast include the following:

• approaching large projects with hundreds of help topics located in multiple sources
• how Flare and RoboHelp handle large projects (latency issues)
• AuthorIT, always a hometown favorite
• techniques for breaking down silos
• how she transitioned from technical communicator to information architect
• why she moved away from RoboHelp to Flare, and the problems she found with both
• the sluggishness she encountered with large files
• how to approach the information architecture for a project with 2,500+ topics
• tips for creating more effective searches
• implementing Madcap Feedback server for keyword search metrics and and comments/feedback
• overcoming problems of findability
• integrating knowledge base articles with read-me’s and technical guides and user guides maintained in 5 different formats
• creating a master search for a massive help project
• topic-based browsing in the TOC versus search
• configuring synonyms and keyword concepts
• limitations with Flare’s search
• techniques for gathering feedback from users
• importing Word files into Flare
• cleaning up RoboHelp code before importing into Flare
• getting buy-in from different departments (teambuilding)
• Flare’s unexpected learning curve
• choosing software based on the needs of your project
• considering cost when selecting software
• several hidden gotchas in Flare
• working with concept keywords in Flare to improve the searchability

Podcast Sponsors

MadCap Flare is the most versatile XML-based Help authoring tool on the market, with thousands of customers using MadCap products including Microsoft, Google, HP, GE, yahoo and the list goes on. Check out Flare version 3.1 and a host of other new tools at at madcapsoftware.com.

Adobe – The Technical Communication Suite software offers a complete solution for authoring, managing, and publishing interactive instructional information from technical documents and books to online help systems, knowledge bases, interactive training, and eLearning content in multiple formats and languages. Learn more here.

Intro music is Velveture by Ocean Alexander

Upcoming Training on WordPress

Are you interested in learning more about self-hosted WordPress blog sites? If so, let me know by sending me an email (tomjohnson1492@gmail.com). I’m planning to offer some training in the upcoming weeks. Training will cover everything from the basics, such as using posts, pages, categories, and tags, to PHP calls and CSS tweaks.

Madcap Flare

I just finished converting a help file (which I originally created using RoboHelp 7) into Flare, using version Flare 3.01. I also added quite a bit of content and other enhancements to the help. While working with Flare for about a month, I took careful note of all the things I liked and disliked about Flare. This post is a compilation of my notes.

I also rated the importance of each item on a scale of 1 to 5. In my system, 5 is extremely important, and 1 is relatively trivial. I arranged the numbers in general order of importance. Here are my lists.

Love about Flare

1. Clean Word output. When I generate printed documentation, the Word output looks almost perfect, especially the numbering and margins. Although there are still some minor things to edit and check, the Word output is definitely impressive. This is the most important feature for me because I want to single source my content. 5

2. Index words embedded mid-topic. I can add index keywords half way through the topic if I want. Embedding index keywords in topics (rather than just within headings) is critical if you have numerous hotspots on a page or have long pages and plan to generate printed output. You’ll want your index words to point to the right pages. Indexes are key features in print manuals — and indexes need to be accurate. 5

3. Cross references. The concept and implementation of cross-references (as opposed to just hyperlinks) is a major step forward for single sourcing — at least when printed documentation is one of your outputs. When I generate my Word target, cross references I created in Flare indicate the correct page numbers of the topics they link to. Except for a bug about cross references pointing to bookmarks in drop-down hotspots, the cross reference feature works pretty well. 5

4. Persistently open style pane. When I press F12, Flare’s style pane opens and stays open. The styles that appear are related to text I’ve selected. If I’m in a list, list styles appear. If I’ve selected a word, character styles appear. If I’m in a paragraph block, paragraph styles appear. And I can quickly select the style I want. 5

5. Drop-down twisties. The drop-down hotspots have little twisty arrows at the top to indicate their state — collapsed or expanded. When the drop-down text is expanded, the twisty arrow points down. This creates more clarity for the user about the text on the screen. (Note: In the image below, I customized my twisty images.) 5

6. Thorough integration of CSS standards. CSS is used to style everything, even the Webhelp skin and printed output. CSS is a standard that isn’t a proprietary Flare format language, but rather is knowledge you can apply in many aspects of web design. Except for the special table style editor, standard CSS determines the display for nearly everything in Flare. I love the exposure to CSS. The more masterful I become with CSS, the greater control and style I have over the way my content displays. CSS is a topic that is rich and deep. Mastering this styling language allows you to go beyond Flare and use your knowledge in other applications (for example, WordPress, a blogging platform, uses CSS to style the look and feel of its display). You can also manually insert more advanced CSS styles than what you find in the Flare CSS editor. 5

7. Multiple mediums for stylesheets. Each stylesheet can have a print and online medium (and additional mediums too). This allows me to define one style for print output and another style for online output without having to create separate stylesheets. Where styles are the same, I leave the setting as default and it applies the style for both print and online mediums. Very convenient. 5

8. Lists functionality. The lists button and functionality simply works, and I don’t have to resort to any tricks to continue lists or do anything special to have them start at a certain number. 5

9. Flawless display in both Firefox and Internet Explorer. You don’t have to worry about discrepancies for Flare’s Webhelp display in Firefox and IE. It looks good in both. The Webhelp frames fully load and lists look similar between the two. 5

10. Mix-and-Match ability with targets, TOCs, and stylesheets. Probably one of Flare’s strengths is the ability to have multiple targets (outputs), table of contents, and stylesheets, and to be able to mix and match them for your project needs. 5

11. Open-and-close speed with topics. The tabbed interface with topic editing is nice, and the topics open and close quickly, even when I have 50 tabs already open. There’s almost no delay. 5

12. Drop-down text. Drop-down text (hotspots) work flawlessly, without any formatting quirks or hassle. They’re easy to apply and remove (“unbind”), and you don’t have to deal with copying and pasting text into a pop-up dialog box, hoping the formatting isn’t thrown askew. 5

13. Automatic updates of changed file names and locations. When I update a file name or location, Flare updates all references to that file. 5

14. Breadcrumbs. This navigational map for users helps them understand where they are in the help maze. The path for the breadcrumbs is generated from the TOC, rather than the folder structure. You can style the size, color, and path symbols (> or |) of the breadcrumb. 5

15. Editing index entries. Whoever designed in the indexing interface and functionality deserves a special dinner, because it’s about the most usable feature in the entire application. As you type new index keywords, a drop-down list appears showing index words you’ve already typed (which is helpful for knowing whether the keyword should be a sub-keyword). Additionally, it’s easy to see all your index words, and then go directly to them in the topics so you can update them. You can also cut and paste the index keyword chunk wherever you want to move it. 5

16. Interface flexibility. It’s easy is to drag and drop and redock the panes. I have two monitors, so I often drag some panes onto the second monitor to make more space. 4

17. Active user forum and knowledge base. Flare has a strong community of enthusiasts who are eager to help out and answer your questions. Sometimes the number of users and their enthusiasm/participation in forums is as important as the tool. For example, WordPress’s strength lies in its passionate community of users. 4

18. Printed output intelligence with headings. If I have an H1, H2, and H3 heading in my online help, when I output to Word and use the book as the heading title, Flare automatically shifts the headings down to accommodate the tiered structure, using the book as H1, the topic title as H1 as H2, etc. 4

19. Madcap’s company size and focus. The company isn’t so big that you can’t get your voice heard by someone who matters. The company’s entire focus is on technical communicators. You can email Mike or Jennifer directly. 4

20. Shortcut for editing images. I can open and edit images in SnagIt or Photoshop directly from the Content Explorer pane. When I save my edits, they immediately appear in the image. 4

21. Windows Explorer Integration. I can open any files in Windows Explorer (directly from Flare) to see or add content. Quite amazingly, even edits made in Windows Explorer (for example, renaming an image file) are applied in Flare. The application doesn’t freeze up when I make changes in Windows Explorer (however, if you relocate a topic into another folder via Windows Explorer, Flare doesn’t auto-update the location). 4

22. Styles for drop-down heads. The drop-down head is the first line of a drop-down hotspot (Flare uses the term drop-down text). You can apply styles to the drop-down heads so that your printed output styles them as headings, if you want. This is key for single sourcing because obviously the drop-down text will be expanded in the print target. 4

23. Accordion stacking and organization of content. The accordion stacking of the panes in the interface works well to show and hide content I need. Additionally, the general organization of topics in the Content Explorer and Project Explorer makes sense to me. 3

24. Content Explorer filter. The filter drop-down in the Content Explorer allows me to limit my view to only certain types of files. For projects with hundreds of files, this filter is really helpful. 3

25. Flare’s online help. Flare’s help is comprehensive, context-sensitive, and interactive. I can comment on a topic if I have something to add or say. It seems like the help file was written by people who actually write help. I also like the “What’s Next?” topics that often appear at the bottom of a topic. While there are some gaps, particularly in terms of how to style the content, Madcap’s help file is overall decent, especially combined with other resources, such as the knowledge base and user forum. 3

26. Detachable tabs. I can detach and float a tab over to my other monitor, such as the TOC. With the TOC on my other monitor, I can navigate the help either through the Content Explorer or the TOC. I like that I can completely dismantle the interface and reassemble it in the layout I want. 3

27. The robustness of the tool. With all the functionality and customization possibilities, Flare is a tool I won’t grow out of. Sure the learning curve may be time-consuming, but with sophisticated features and complex outputs, some study time is expected. 3

28. Collapse, expand, and print buttons in the Webhelp toolbar. For all those drop-down hotspots in your content, it’s nice to collapse or expand them with nifty toolbar buttons. You don’t need to code your own special javascript for this built-in functionality. And they added the print button by default, which seems obvious to include but was missing in RoboHelp. 3

29. Intelligent cursor behavior. I have a love/hate relationship with the cursor. I love it when I can use the arrow keys to escape a table or conditional tag or other formatting. Otherwise I generally hate it, but have learned to live with it and recognize its utility at times. 3

30. CSS editor filter. The CSS Styles editor also has a filter, which is essential as well because the number of styles for any given project can be daunting and this filter makes them manageable. 3

31. Smart index keywords based on TOC builds. If the target of your TOC excludes certain topics, no index keywords embedded in those topics appear in the index. 3

32. Error log when generating output. When I generate an output/target, Madcap let’s me know if there are any errors, such as broken links or missing files. It allows me to save the error log as a report I can view later. 3

33. Perceived lack of company bureaucracy. When I offered to advertise Flare on my podcast for a free copy of Flare, I received a license for it within a day or two. I can contact a human quickly, and in fact whenever I sign up for a trial version or a webinar, someone calls me to ask if I have questions. 3

34. The mysterious-looking structure bars. The structure bars on the left of topics do come in handy when you’re trying to see what formatting is applied to blocks of text, or when you’re trying to manipulate blocks of text. 3

35. Internal text editor. If I don’t like the CSS Style Editor, I can edit stylesheets using the built-in text editor. As much as I appreciate the CSS Style Editor interface, sometimes I’d rather edit the styles manually with the text editor. It’s nice to have this text-only option rather than opening the file in a backdoor method. 3

36. Absence of erratic spacing in the Webhelp output. I love that my Webhelp output doesn’t have random spacing errors (like tabs that snuck invisibly in), such as what I occasionally encounter with RoboHelp. 2

37. Real rather than virtual folders. The folders in the Content Explorer pane are real folders in Windows Explorer. When I package up my help, I don’t have any surprises about the locations of the files. 2

38. Conditional tagging functionality. The builds and exclusions are intuitive and easy to apply. Additionally, the structure bars show the tag color as well. 2

39. Mark of the Web. This little feature allows me to generate and view the Webhelp on my computer without that annoying Microsoft Internet Explorer security information bar blocker getting in the way. 1

40. Image resizing. I can change the size of my images by dragging an image edge directly within the content window. 1

41. Table styles. I can create tables with alternating color rows. The only drawback is that the table styles are non-standard CSS format that competes with any table styles in the regular stylesheet. 1

42. Smart printing of online topics. When you print a topic from your Webhelp file, the print medium of the stylesheet is applied. Nice touch. 1

43. Adding Related Topics. The usability of this feature is a complete no-brainer. My only complaint is that you can relate a topic to itself, and instructions for styling the pop-up were missing. 1

44. Full skin previews. While you’re customizing your Webhelp skin, you can see previews of entire skin, rather than just a section of the skin. (My only complaint: the Mark of the Web doesn’t kick in with this preview, so IE gives you the information blocker bar.) 1

45. Conditional table selections. I can conditionally select table rows or columns and include or exclude them without a gap showing in the output. 1

Hate about Flare

1. Can’t create cross references to bookmarks in drop-down heads. Let’s say you’re using drop-down hotspots to consolidate multiple tasks in a single topic. And you want to refer to those specific drop-down hotspot headings with cross-references in other topics. Online, it may not be an issue because the drop-down hotspots appear neatly grouped (collapsed) together. But in print, they span multiple pages. Well, here’s the bug: you can’t create a cross-reference to a bookmark when the bookmark is a drop-down hotspot. The result is an avalanche dump of all the drop-down text into your cross reference link. I did devise a workaround that involves combining hyperlinks with cross references and conditional tags. It works well enough, but this bug is still a hassle to what would otherwise be dream functionality. 5

2. Confusing table styles. Flare provides a table editor that allows you to produce advanced styles for your table, such as alternating rows. However, styles for this table are housed in the table stylesheet, whereas your other styles are housed in the regular stylesheet. Sounds simple, right? Wrong. The regular stylesheet also provides table styles, so if you have conflicting table styles between the two stylesheets, display problems occur. Additionally, it’s not clear where you’re supposed to set styles for the table data, table headers, and table margins. The help file is quiet on the topic, and the user forum experts say to use the regular stylesheet for some table styles, and the table stylesheet for others. Overall, Flare makes it tough to create several classes of tables that are intended for both online and print formats. In the end, I skipped using the table stylesheet and manually edited the regular stylesheet to include the table styles I needed. 5

3. Ambition without completion. I wish Madcap would have focused their development efforts on fixing the bugs, usability issues, and functionality in Flare rather than ambitiously moving ahead to create a handful of new products (especially duplicate products, where other apps already exist). This is the most frustrating feeling — knowing that cross-references don’t completely work in version 3.1, and then receiving an email from Madcap announcing a completely new product. To be honest, I wish Madcap would have merged with TechSmith and incorporated SnagIt and Camtasia into Flare. Both companies need each other’s products. 5

4. The deceptive Quick Search field in Webhelp. The Webhelp toolbar provides a Quick Search field that, at first glance, would appear to search for words in the entire project. When you enter a few searches, I thought it was broken until I realized it was only searching for keywords in the visible topic — which is hardly desirable. I want the project-wide search to be immediate and visible to users, as well as the Table of Contents. 5

5. The learning curve. I was pretty familiar with RoboHelp, and while Flare markets itself as a RoboHelp replacement tool, it took me several weeks to feel comfortable with Flare. I actually like learning new tools, but I was consulting the help file every 10 minutes. I have more than a dozen pages of notes on how to do things in Flare. 5

6. Poor Webhelp toolbar graphics. The buttons on Flare’s Webhelp skin are not visually impressive enough to wow customers. They aren’t embarrassing either, and they are easy to modify or swap out. Still, I could pay a graphic designer under $1,000 to create an icon set that would be significantly more attractive. 5

7. No labels for Webhelp toolbar buttons. Flare’s Webhelp has a plethora of buttons (granted, you can choose the buttons you want to appear on the toolbar). It would be great to add some labels below the buttons. While you can select labels to apply, the default location for the label is directly on top of the button. It’s not clear if you’re supposed to position the label’s location via the stylesheet (if so, what style name?) or if you’re not supposed to select both a button and a label. It would be nice if the default label location was at the bottom of the button. (Update: for more info on Flare’s toolbar and labels, see this forum thread.) 4

8. Quirks with deleting things. Sometimes if I select and delete things, I get unhandled exceptions and the application crashes. Other when I select and try to delete something, nothing happens — probably because I’m not using the cursor correctly. (Deleting objects using the structure bars is the preferred, more trouble-free way. But structure bars don’t appear for character level formatting.) 4

9. Abundance of unfriendly error messages. I’m seeing a lot of error messages, most of which seem written by programmers. For an application that is in version 3, that’s too many error messages. A lot of times the error messages appear when I incorrectly select something and try to delete it. Other times I’m sure I’m doing something illegal, just not sure what. I made a collage of the error messages here. (I have to admit that some errors are probably due to improper code from RoboHelp when I imported the RoboHelp project into Flare. But still…) Click the image below to enlarge the thumbnail. 3

10. Lack of integration with Captivate/Camtasia. If I don’t want to use Mimic (because I prefer tools like Camtasia or Captivate, which I happen to think are miles ahead of Mimic), there’s no direct way to import Flash or non-HTML files into Flare through the interface. You have to open the content folder in Windows Explorer, paste in your html and flash files, and then double-click the topic to initiate an HTML to XML conversion wizard. Then it plays. Shouldn’t an import HTML feature been built-directly into the interface? I don’t want to be forced into using other Madcap tools. 3

11. The unintuitive, weird cursor. The cursor takes some practice to figure out. You wouldn’t expect that such a common feature would be a conundrum. To be honest, sometimes I love the cursor, other times, such as when I’m selecting character-level things, I hate it. (In the image below, I pressed the down arrow to change the cursor state to escape the current paragraph block and format.) 3

12. Lack of pixel size information for images. When you resize an image, you can’t see the actual pixel size of the image. It’s important to know the image’s pixel size if you’re exporting the image to a printed target, where margins are important. Why not just resize to a specific dimension prior to inserting into a Flare topic? Because images resized in SnagIt or Photoshop look fuzzy; images resized in Word (in the printed target) look crisp. So as long as you insert images at their full size in Flare and then drag them smaller, they’ll look sharp in Word. The problem is, I want my images in Word to be uniformly sized, which is hard to specify when you’re just dragging the image smaller using the resizer. (If you use Capture, apparently you won’t have this problem.) 3

13. The learning curve. Despite my familiarity with RoboHelp, I felt Flare had quite a learning curve. I’m still learning a lot. Tip: Don’t try to learn Flare in a crunch, or you’ll set yourself up for high blood pressure. Give yourself several weeks to get comfortable with Flare. People usually wait to convert to Flare until they’re forced into it (such as when they realize their RoboHelp’s Webhelp doesn’t display correctly (by default) in any other browser except Internet Explorer). Then it’s crunch time to make your help file look right. Mixing a quick turnaround of deliverables with a significant learning curve will frustrate you. 3

14. Lack of instruction about the MiniTOC. The MiniTOC was a new concept for me, and instructions in the help lacked some critical details about how this feature does and does not work. Basically, the MiniTOC provides a table of contents for topics within your online book. But the topic that the MiniTOC is embedded on can’t be listed in that TOC book or else the MiniTOC won’t show. You do, however, link the TOC book to the topic with the MiniTOC. (Wasn’t that obvious? ) I find the MiniTOC a cool feature, particularly as a placemarker in the breadcrumb trail. It just took a while to figure out. 3

15. Assumptions about my understanding of CSS. I feel like the designer of Flare was a CSS guru who thoroughly understood classes, selectors, attributes and rules of inheritance with CSS. Although I am somewhat familiar with CSS, I’m not a guru by any means, and I would appreciate more instruction and detail about it. I guess there are myriad online tutorials for CSS on the web, but a special section in the help, outlining the most common CSS attributes used in online and printed help files (for example, how to style a note or tip), would be greatly appreciated. 3

16. Absence of drag-and-drop functionality for proxies. The way Flare works, you have masterpages (templates) that you add proxies (special sections, like bodies and indexes and miniTOCs, as well as page footers and headers) to. The proxies on the masterpage are applied to all your topics (if you select that masterpage for your project). However, getting the proxies and footers/headers correctly positioned and aligned on the masterpage is tricky. For example, to add a footer that has an alternating right and left alignment, with nothing showing on the first page, you add three footers right on top of each other. While you’re adding them, you have to know how to manipulate the cursor so that you escape the previous footer, or your next footer will be included in the previous footer, driving you crazy when you try to interpret the output. 3

17. Conditional text seems flaky. The conditional tagging I’ve applied to text disappears when I apply links to the text. Then when I select my conditionally tagged text to see the tags, at times no check marks appear next to the conditions I selected. (Looks like someone else had this problem too.) 3

18. Can’t have the stylesheet simultaneously open in Dreamweaver. If I open the stylesheet in Dreamweaver while I also have Flare open, the stylesheet file begins to show numerous MFCA.tmp files in place of the .css file. Maybe the .tmp files are harmless, but it makes me uncomfortable. Why not use the built-in text editor, you ask? Because Dreamweaver provides great little prompts for CSS attributes. And Flare’s built-in text editor lacks word-wrap formatting. 2

19. No public tracking of my bug submissions. Sure this would be a groundbreaking feature for companies, but when I submit a bug to Flare, I want to know what happens to it. Does someone read it? Do they say oh yeah, we’re already working on it? Or, sure that’s coming in the next release. I’d love to track my bug/enhancement submissions, or to be notified in some way about how it’s being handled. 2

20. Confusing stylesheet commands for cross-references. Granted, the cross-reference feature is pretty cool, but figuring out the style commands could be more intuitive. It would be nice to select from a drop-down box in the format column, rather than typing {para} or some other command. {para} generates the first paragraph of any heading or bookmarked text. {page} generates the page number. {paranum} generates the first numbered list of the paragraph. {parakeet} generates a picture of a parakeet. Just kidding. 2

21. Incorrect WYSIWYG display for printed styles. In the WYSIWYG editor, you can choose to see how the topic will look with different stylesheets applied. However, the print medium’s display didn’t show the correct margins for my tables. 2

22. TOC centering quirk in navigation pane. If you have a long table of contents entry in the Webhelp, selecting that entry centers the TOC entry, making the books on the left hidden. RoboHelp has the same problem. Why don’t they make these topic names wrap by default? The workaround is to widen the navigation pane and shorten your topic titles, or to uncheck the Auto-Sync check box. 2

23. MadCap Analyzer is a separate product. MadCap Analyzer would be a beautiful addition to Flare, providing comprehensive reporting and giving you style suggestions that will make your project more efficient. Unfortunately, rather than rolling Analyzer into Flare, it’s a separate product you have to buy. 2

24. The CSS Style Editor. While I take my hat off for the attempt at producing such an editor, the actual execution could be more usable. Attributes for styles in the Simple Editor mode appear in a long list of columns, forcing you to scroll right about a foot. When you double-click a style, a dialog box with side tabs appears, but the side tabs don’t include all the options from the columns. Additionally, many columns are irrelevant to certain styles, and it’s somewhat of a guessing game as to which attributes correspond to which styles. The Advanced Editor provides more comprehensive display, but why have the dual modes? 2

25. The term “proxy.” Proxy is not a common term. In Flare, proxy is used to identify sections of a template that you apply to your content. The word kind of fits, but not really. Maybe some more brainstorming could have eliminated my shoulder-shrug when I saw this term. 1

26. Ability to cripple your project. If you do a find-and-replace for a code tag across your entire project, and you replace the wrong tag, you could cripple your entire project. XML is strict in that errors with tags make the topic completely unshowable. (You can still edit the text in the built-in text editor and tediously fix the tags.) 1

27. Selecting one topic at a time in the Content Explorer. The Content Explorer, where all your topics and images are stored, only allows you to select one object at time (within Flare’s interface). If you’re trying to drag an item from the bottom of the pane into a folder that’s at the top of the pane, and that top folder isn’t visible, you can’t do it. The pane doesn’t automatically scroll up with your mouse. To move multiple objects simultaneously, you have to open the content within Windows Explorer. 1

28. Lack of keyboard controls. Two keyboard controls I frequently use are absent in Flare: the Ctrl+Backspace to delete a word, and the Shift+Return for a soft return. [Update: I'm not sure why I thought Shift+Enter doesn't work -- it does.] 1

29. No quick code view tab. I love flipping back and forth between a design and code view. Many editors offer this, but Flare makes it harder to see an editable code view. You have to right-click the topic and select View in Text Editor. The text doesn’t wrap, so you have to use your scroll bar to move right. The designers may have purposely made it difficult to edit the XML code (for fear that users would corrupt their own help files), but to be honest, the XML looks almost identical to HTML except for the declarations at the top. Would a code view tab have been that harmful? 1

30. Silent failures for printed targets. If you have an error in a topic (an error which you can’t see), sometimes a topic won’t generate in the printed target. One of my topics was quietly missing from the printed target. I checked the code in the topic and saw some tags that looked odd. When I created a new topic and removed the tags, it generated correctly. I just assumed all the topics appeared in the printed output. (To be fair, the corrupt code may have resulted from the RoboHelp import of the topic.) 1

31. Too many search results from the help file. I enjoy the thoroughness of the help, but the number of search results is perplexing. It seems like there are 300 results for every search. I guess 300 is better than none, and of course I can narrow the search string. 1

Conclusion

Despite all these problems, I still really like Flare, and would definitely recommend this tool as the leading online help tool on the market today. In comparing it with RoboHelp, Flare wins hands-down for functional superiority. However, you should know what you’re getting into.

I’m also hoping that by publishing this list and exposing some of the problems with Flare, Madcap developers will turn their attention to fixing them. Or perhaps expert Flare users will explain tricks around the problems, or help me see where I am wrong. I went to all this trouble because I like the tool and want to see it improve.

Overall, Flare scored 152 love points and 86 hate points. This means I love about twice as many features as I hate, which is always promising when selecting a help authoring tool.