Notice that I said “organize.” You’re still organizing your content, but on a smaller level. Rather than organizing topics within groupings or folders, you’re organizing the words within the topics. To make the topic visible, you have to organize the words in a way that maximizes visibility in the search.

But here is where things get confusing. Almost no one understands how search works. Google’s search works differently from Flare’s search. Flare’s search works differently from WordPress’s search. I’m guessing that the search in RoboHelp differs from the search in Author-it, which differs from the search in DITA-produced Eclipse help, and so on.

Each search engine has a unique algorithm that sorts and ranks information based on a set of variables and other factors, much more than simple keyword frequency. Here’s the key point: you can’t optimize search until you understand the search algorithm you’re optimizing for.

Google’s search algorithm

Although Google’s search algorithm is complex, it’s unquestionable that Google’s search results are based on some of the following factors:

• The number of links pointing back to your site
• The authority of the sites pointing back to your site
• The text used in the links pointing back to your site
• The location of the keywords the user is searching for, especially in the title and h1, h2, h3 tags
• The frequency of the right keywords that the user is searching for
• Your own site’s page rank

What about meta keywords and title tags? Not that important. You could stuff a ton of keywords into the header of your topic, but Google has been gamed with that trick long ago, so it ranks these keywords low. The genius of Google’s search stems from the collective wisdom of hyperlinks.

WordPress’ search algorithm

According to Lorelle Van Fossen, WordPress orders search results with the date as a major factor:

When you search in your WordPress blog, your search results are listed chronologically. Not by “most likely”, “most popular”, “most frequent use of the phrase”, or even alphabetically, just by date. And the chronological order runs from most recent to oldest. If the most likely post to provide the information the user is searching for is older, they will have to scroll towards the end of the list to find the most likely candidate for information. What are the odds they will, huh? This frustrates me no end.

Another frustration with WordPress searching is that it only searches posts. It does not search comments nor Pages. Only post content.

Notice that while links pointing to your content factor high in Google, these same backlinks are non-factors in the WordPress search algorithm. In WordPress, the date of the post seems to matter most.

Madcap Flare’s search algorithm

Since Flare is the help authoring tool I’m currently using, I’ll dive into its search algorithm with more depth. According to Rob Houser in Flare Tip: How the full-text search works, Flare’s search weighs the following three factors with the most significance:

• Exact matches
• Frequency of the words
• Location of the words

Rob explains,

Flare ranks exact matches of the term the user enters higher than partial matches. An exact match uses the same form of the term (for instance, an exact match for “deleting files” would be “deleting” or “files”). A partial match may share the same root word as the original search term, but the terms aren’t exactly the same (for instance, the user might search for “deleting files” and the search would also find “delete”, “deletion”, “file”, and “filed”).

I’m not sure where Rob is getting his information, whether through experimentation with Flare or conversations with Flare developers. But let’s assume Rob is right. There are still many questions unanswered, namely how to create an exact match. If the topic title doesn’t provide the exact match, how do you create the match?

The Problem with Using Index Keywords

Flare doesn’t have a section where you can stuff a file with meta keywords. But you can stuff a topic with index keywords. Index keywords are included in the search algorithm. (Concept keywords are excluded, by the way.)

However, using index keywords as meta keywords presents a dilemma. If exact matches factor highest in the search, you should add index keywords according to the phrases you think users will search for in the help, right? But the way users enter keywords in search boxes differs from the way users browse an index.

With Flare you’re forced to make a decision about how you want to use the index keywords. If you use index keywords to beef up your search, your index will look random. If you choose index keywords for readability in a traditional index, you cripple the search.

Let me give an example. Suppose my topic is “Properly Delivering a Burn Notice.” Users searching for this topic might enter the following phrases:

• burn notice
• deliver burn notice
• drop off burn notices
• burn notices sending
• how to present a burn notice
• cutting off undercover agents
• severing ties with field agents
• burn notice protocol
• best way to handle burn notice
• give burn notice to operatives

Because exact matches factor the highest in Flare, it’s important to include these phrases as index keywords, and to insert those index keywords into the highest ranking location in the topic — that is, inside the h1 tags of the topic title.

But if I’m going to also produce an index in the help file or in the printed guide, the keywords and phrases need to be written and ordered differently. A typical string of index keywords might look like this:

• burn notices, delivering
• protocol, for burn notices
• field agents, delivering burn notices
• operatives, terminating
• tactics, presenting burn notices

When you browse an index, you look for the main word first, which is usually a noun. Users don’t usually browse to “give” or “deliver” when looking for a topic in an index.

But when users search, they usually do include verbs to lead off the phrase. I tend to search for exactly what I’m trying to do. If I want to download an mp3 file of a James Bond soundtrack, I search for “download mp3 James Bond.” If I want to figure out how to stop water leaking through my window well cracks, I search for “stop leaks to window wells.” I lead with the verb.

Stems?

Another question is to determine how the search algorithm handles stems. Exact matches factor highly, so when I have a phrase like “drop off burn notices,” do I need to add drops off burn notices, dropping off burn notices, dropped off burn notice, drop off burn notices, and so on for each of these search keyword phrases?

I wrote to Madcap to ask them for this information, because it’s not in the help file. They replied that the search will automatically look for partial matches, so if I just include “drop off burn notices,” Flare will look for partial matches with the other verb forms. But an exact match still trumps a partial match in search engine weight.

What? It’s not in the help!

I felt a little bewildered that Flare’s help, which is comprehensive and complete in almost every way, had nothing to say about one of the most important elements of help authoring: how to influence the search to increase topic rank.

And then I realized something ironic. In the application I’m documenting at work, search is a key feature, included in four separate places in the interface. And yet beyond keyword matches, I have no idea how the search algorithm works.

Blog Sponsors

• 3Rabbitz book
• 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

jQuery is the new Javascript. It provides smooth functionality that shows and hides components, slides objects around, and animates graphics in a sexy way. As an example, ProPhotoBlogs’ support section incorporates jQuery functionality. And the drop-down menus on Will Sansbury’s site are also jQuery driven. Here are a few jQuery animation effects. And slide-down effects. And fade effects.

Alistair says he feels satisfied he made the right choice about adopting Flare as a help tool because of this extensibility. Because of the XML and CSS standards that Flare is built on, Alistair can add a reference to the jQuery script in the header, add functions in the page body and toolbar, and hook into other technologies to customize the display.

For detailed step-by-step instructions on inserting functions into Flare’s Webhelp toolbar, see Alistair’s post, Adding function buttons to to the Madcap Flare Web Toolbar.

I like Flare for much of the same reasons as Alistair. I haven’t integrated jQuery scripts into Flare yet. But knowing that I can do it if I wanted to is encouraging.

The next question is what functionality we’re missing from Webhelp. Is jQuery just the latest gee-whiz, bell-and-whistle technology? Or is it functionality that will persuade users that the help is worthwhile?

Alistair says he created a button that shows a direct link to the topic the user is viewing. And he hooked into a custom glossary database. He also integrated his own show/hide functionality and a bookmarks feature. Granted, some of that functionality already exists to some degree in the existing Webhelp buttons, but Alistair’s company had custom needs.

One button I’ve added to Webhelp is a Contact button that allows the user to send feedback to the project team. I would like to incorporate jQuery scripts to make screencasts pop-up in a modal that dims the background. I’d also like to make screenshots expand to full size when the user clicks them (similar to Flare’s new thumbnail feature). The way graphics slide down smoothly with jQuery is more elegant than the built-in drop-down hotspot functionality Flare provides. (I imagine you have to work in the code view to integrate all of this.)

I’m not sure to what extent other tools can hook into the same technologies. But it is important to have this potential — so that help authors can keep pace with the developments and technologies of the web.

To listen to Alistair Christie’s podcast on extending Flare with jQuery, see Unscripted Screencasts and Flare Extensibility.

Blog Sponsors

• 3Rabbitz book
• 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

Carmen, a student in a technical management program, found me by searching for “technical writers” on Yahoo.com. Fulfilling an assignment in a Career Development course to contact someone working in the technical writing field, she asked me 13 questions about technical writing careers. She’s currently a repair technician who has wanted to enter technical writing for years.

Her questions and my answers are below. Please feel free to build on my answers in the comments section below the post.

Job-Related Questions about Technical Writing

What do you like best about your position as a Technical Writer?

I like the combination of writing and technology. I majored in English and love to write, but careers for writers are usually low-paying. I also really like technology — websites, blogs, gadgets, social media, cyber-utopian imaginations, etc. Technical writing combines my two main interests — writing and technology — in almost seamless ways.

What kind of impact has this position had on your lifestyle?

Given that technical writing jobs pay a decent salary, I’ve been able to support a family with three children and an extremely hard-working stay-at-home mother. I couldn’t have done that had I gone into other writing fields. (For example, here’s a blog about a guy who earned a degree in creative writing but couldn’t put his skills to use, so he started delivering pizzas.)

I’ve found that working as a technical writer has sharpened my troubleshooting skills, given me greater patience and technical familiarity, and has deepened my awareness and interest in technology. For example, my wife jokes that computers — when they seem to work against her — are the Antichrist, and sometimes when she can’t get something to work, she’ll actually slam the keyboard or throw the mouse. Well, I’ve learned that broken websites, procedures that don’t work, and confusing code can all be overcome with some patient problem-solving. This is a skill I developed as a technical writer.

Technical writing also gives me time to pursue other hobbies in the evenings and weekends. Sometimes finishing documentation for a project can require you to sacrifice a few evenings, but by and large technical writing is an 8 to 5 job. That’s nice — not a lot of stress, and it’s not as if people die (regularly) because they can’t figure out the software, unlike careers in medicine.

What advice would you give to someone just entering this career track?

I highly recommend pursing technical writing as a career, especially if you majored in English or Writing. I say English or Writing because much of a technical writer’s day is spent writing (or preparing to write or editing what you’ve already written). Granted, instructions aren’t creatively fulfilling, or even interesting, but you’re still shaping complicated information into easy-to-understand, well-organized text. You’re creating something out of nothing. You are, in fact, writing.

But skill with words isn’t enough (and actually, you don’t have to be very skilled to write sentences like “Click this button,” “Select this from the dropdown box,” and so on). You also need technical aptitude. Does your blood pressure shoot up when you can’t figure something out? Or do you patiently find a way to solve the problem? If you’re a problem solver, technical writing is for you. You’ll be solving technical problems a good part of your day, as you experiment and explore and test how software functions, or might function (or is supposed to function).

To sharpen your technical skills, learn at least three types of programs: a graphics tool (such as SnagIt), an online help authoring tool (such as Madcap Flare), and a video capture tool (such as Camtasia Studio). Create some sample documentation so you can show employers your skills. Start a blog about technical communication so you can demonstrate your enthusiasm and knowledge to your employers. Take responsibility for your own learning, rather than relying on others. Also, get involved in your local STC chapter.

You might also see this post I wrote: “How to Break into Technical Writing”

What kinds of tasks do you complete during a typical day or week?

It’s your lucky day. I’ve already written an incredibly detailed post about this here: “Could you please tell me what the job of a technical writer is like?”

What types of advancement opportunities are available for entry-level candidates in this career track?

Interesting question. Here’s a great podcast on the potential career track for technical writers. Traditionally, junior technical writers become senior technical writers. Then they become managers, or often turn freelance, or do consulting. Some transition into business analysts or project managers, or move into other technology-related fields.

There’s some debate as to whether technical writing is a transitional job — something you do as you’re working your way into another role, such as business analyst, usability specialist, information architect, or project manager. Many people see technical writing as a stepping stone into something else.

Company-Related Questions about Technical Writing

What is the corporate culture of your company?

The corporate culture where I work couldn’t be better. I love the team environment, working with other dedicated and talented individuals who are inspiring and helpful (for example, they give access to what I need, answer questions, provide demos, review my documentation, and keep me up to date on changes). There aren’t any political battles or bitter attitudes. It’s really a fun place to work, especially since the entire project team is grouped on the same floor. There’s even a foosball table. And the technological setup is top-notch — see my previous post, “Top 10 Workspace Configurations for Technical Writers.”

One thing to avoid in corporate cultures is an overbearing bureaucracy, where a thousand regulations and procedures prevent you from being efficient. My current work environment is pretty much bureaucracy free.

I’ve worked in other companies where the environment was more challenging. For example, at one place, it took me two weeks before I was given access to the Intranet. In another place, I felt like I had an abundance of unnecessary meetings all day. But despite these challenges, the other environments have also been decent. I’ve always learned a lot in every situation I’ve worked, regardless of the corporate culture.

For alternative experiences, see this comment by Joseph K on a previous post.

Does the company promote or encourage continuing education?

Certainly my company promotes continuing education. They’re sending me to a couple of conferences this year — Doc Train West in Vancouver and the STC Summit in Philadelphia. (Granted, I’m presenting at both conferences.) They also buy me whatever software I need.

What type of training programs does the company offer?

I hinted at this earlier: you’re responsible for your own learning. I have some intelligent, helpful colleagues who teach me a lot — not just about software, but business process and documentation strategies. But I think ultimately, you’re in charge of your own learning.

That said, my company pays tuition if I want to take college credits (in any field). I have access to Safari, an online library with thousands of books and tutorials — I’m still exploring that one. I occasionally view webinars related to the software I use. I can order books as needed, and probably attend workshops or other training up to my allotted training budget.

What are some of the goals of the company of the next few years?

Hmmm, not sure how to answer that one on a public blog. But we definitely want to find technology solutions that help people on a global scale perform the tasks of their role more efficiently and powerfully. We want to leverage the Internet platform to provide helpful resources and information to people everywhere. We want to use technology to further our organization’s mission. The same could probably be said of many companies.

Industry-Related Questions About Technical Writing

What kinds of challenges is the industry currently facing?

Outsourcing is one threat, although I haven’t been following it much lately. I once interviewed an Indian technical writer who said the tech writing industry is exploding in major ways in India. In my experience, I think the technical writer works best when he or she is on-site (rather than remote).

Another threat is a crash in the technology sector. With the first Dotcom crash, many technology companies made dramatic cutbacks to survive. Technical writing is often an easy cut, since you can have the business analyst or subject matter experts (SMEs) write the manuals (or simply ask the existing technical writers to do more work, which is common).

Some leaders feel SMEs have the potential to do our jobs, but the results are often disastrous. (Think about instructions that lack any numbered steps, have a full-size screen print on each page, and are written in confusing jargon that assumes you’re half-engineer.)

Who are some of the major and minor competitors in the industry?

Some people think wikis will reduce the number of technical writing jobs (or transform the role of technical writers). The idea is that project members and users will simply write the documentation in piecemeal fashion. However, this idea is one that only works in unique contexts, like the WordPress Codex, and even there it doesn’t work well.

I agree with Craig on Helpscribe that wikis won’t kill technical writing. I actually once produced a help project entirely on a wiki. I was documenting the new SharePoint 2007 platform and had about 75 wiki topics. Just two people made a couple of brief edits. That was it. And with the wiki, it was a pain to style, it didn’t single source, and it was hard to manipulate and rearrange information. Wikis have been around 10+ years and haven’t replaced much of anything (except Encyclopedia Britannica).

For more on using Web 2.0 technologies in documentation, see DMN’s post on “Web 2.0 and Documentation Don’t Always Play Well Together.”

Another competitor is, as I mentioned above, outsourcing technical writing to places like India. I don’t have much experience with outsourced projects, but Charles Jeter wrote an interesting post on the state of innovation in India. I personally have never lost a job to outsourcing. In part it’s because I wear more hats than just a traditional technical writer.

Are there any likely changes that may affect the industry in the next few years?

Here’s an interesting observation. You’re writing me to ask about careers in technical writing. You’re asking me to provide insight on the technical writing industry as a whole. But I’ve only been a technical writer for less than 5 years (been a writer for much longer, though). The interesting thing is that I’m the one being asked for advice, and am giving it. Hundreds of others will find this post and take direction from it.

We’re seeing the rise of amateur content. If you want advice from someone with more authority and experience, you should have written someone like Neil Perlin or Doug Davis. Instead, because I’m more visible in Google, I become the de facto expert on technical writing. That reversal of roles, where non-leaders become leaders, amateurs become experts, and ordinary people become highly visible, will shape all industries dramatically in the next few years.

Another change is DITA, an XML language that allows you to reuse topic-based content. Over the next few years, DITA will become a standard technology embedded into the most popular help authoring tools. This will facilitate single sourcing and enable technical writers to be more efficient. As we’re more efficient, we’ll play greater roles with training, support, and quality assurance. I already wear each of these hats to some degree.

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.

Madcap Flare is one of the most powerful online help authoring tools on the market today. In this podcast, Paul Pehrson, MVP in the Madcap Software forums, talks about Madcap Flare in depth. If you create online help, this is definitely a podcast you should listen to. Paul is a really sharp guy and if you’ve ever participated in the Madcap Software forums, you’ve probably been helped by “Doc-Guy” (Paul’s alias).

(We recorded this interview in-person, since we actually work less than a mile from each other.)

Topics Discussed in this Podcast

• Flare’s XML editor
• Integration of Flare with source control
• How Madcap addresses the entire writer’s workflow
• Generating quality printed output from Flare
• Cross-platform shortcomings
• Thorough integration of CSS standards in Flare
• Flare’s CSS editor
• Flare’s learning curve — how long it takes to learn Flare
• Variables and snippets
• Indexes and insertion of index keywords within topics
• Implementing variables across the entire workflow
• Rewards from being a forum volunteer and moderator
• Madcap Software’s family feel
• Relevance of company size and location
• Mike Hamilton, vice president of product management
• Lingo and the single sourcing of content across images, topics, and outputs
• Lingo’s efficiency with localization
• Madcap’s responsiveness to blog comments and feedback
• Feedback Server and topic-based comments
• Balancing complexity with usability
• Madcap Analzer and Feedback Server
• Product/company image generated by blogs and user forums
• The online help market in 5 years
• Reasons for Framemaker’s stagnation
• Qualities of companies that will succeed in the future
• The best way to learn Flare

Links to Additional Resources

• Paul Pehrson blog
• Six Reasons to Love Flare
• Six Persistent Flare Problems
• Paul’s 5 day Content Reuse Post Series
• Paul’s portfolio site (using Flare to create a website)
• Madcap Software Forums
• Madcap Software home page
• Madcap Flare
• Flare’s Online Help (shows Feedback Server integration)
• Madcap Analyzer
• Madcap Knowledge Base
• Music from Podshow

If you enjoyed this podcast, you’ll also like Charles Jeter’s recent interview with Mike Hamilton.

Paul Pehrson has an excellent post detailing six persistent problems he’s encountered with Flare. Paul introduces his post saying,

I’m a Flare user, and I really, really, really like Flare as a help authoring tool (HAT). It’s a solid program that does a lot of great things. On my recommendation, my company is going to renew our maintenance contract with Flare this fall, and I expect to be using Flare for a while to come.

That said, I think that there are a few persistent problems in Flare that new users should be aware of when they start using the product. None of these are deal-breakers for me, even in the aggregate. Still, I think that these are things that if I had known were problems, I wouldn’t have spent hours banging my head against the wall trying to solve them.

I enjoyed Paul’s post. Every tool has its shortcomings, quirks, and flaws that you don’t experience until you start using the tool extensively. At least now if you go in the direction of Flare, you will be less likely to encounter surprises.