menu   UA Europe - Training & Consulting
UA Europe - Training & Consulting
UA Europe - Training & Consulting

Specialists in
User Assistance

MadCap Flare - tips for improving your users’ search results

Published in ISTC Communicator, Winter 2017.


An important lesson I’ve learned from 25 years of writing software user assistance is that creating great content is not enough—we must also ensure that our readers can find the content they need, quickly and easily. And they’ll typically try to do this not by browsing the TOC or by referring to the index (if one exists), but by using search.

The problem with search, however, is that it frequently yields unhelpful results. During some usability tests I recently conducted, I saw that it was common for users to receive either no results at all, or an excessive number of results that proved almost equally unhelpful. I also observed that users quickly become frustrated by this experience, and give up their search —this led me to coin the phrase "the fragility of search".

In this article, I describe a number of simple steps that you can take within Flare to improve the search experience of your users, and make it more likely that they will actually find the information they are looking for.

Add a custom description

I recommend taking the time to craft a custom description that concisely summarises the key purpose and objectives of each topic. You do this within the topic properties.

Screenshot showing the Topic Properties dialog box

There are two benefits:

  • The description text, although not visible in the published topic, is targeted by the search. So you can increase the ranking of the topic within search results by including words and phrases that you believe your users are likely to search for.
  • The description is shown beneath the topic title in the list of search results, and typically provides users with a more useful and helpful indication of whether the topic is relevant to their needs.

Add index keywords

Index keywords are also targeted by search. For this reason, even if you are planning not to expose an alphabetical index to your users, you may consider assigning keywords comprising words and phrases that don't occur within the text of your topics but that you anticipate users might search on. For example, you might assign the keyword of "flat battery" to a topic containing the procedure for recharging a phone. If users search for “flat battery”, then the topic will appear in the search results even if neither of the words "flat" or "battery" is used within the text. Without the keywords, the search would have returned zero results.

Add synonyms

Another (perhaps quicker and easier) way of avoiding zero results is to create synonym groups of words that mean the same thing. For example, let’s say that you have consistently used “remove” within your topic text, but you know that some of your users might refer to this action as “uninstall” or “delete”. In this case, you might create a synonym group containing these three words.

Screenshot showing a synonym group

As a result, any search on "uninstall" or "delete" will return the same results as a search on "remove". You could also consider sharing these synonyms between multiple Flare projects by using Global Project Linking (see Flare's Help on Global Project Linking).

Add a Search Filter

Search Filters are a great, but a somewhat under-used, feature of Flare. They potentially enable users to filter search results to show only topics of a specific type (for example: task, overview, or troubleshooting). This could be very useful if your users’ searches frequently yield long lists of results that make finding what you want difficult. The problem with search filters (and the reason for their under-use) is that, due to the way they are presented within the HTML5 skin, their function is neither obvious nor intuitive to the end user. For more information on search filters, see Flare's Help on Search Filters.

Train users to search effectively

I believe it is important to ensure that users are aware of the advanced search conventions that are available—particularly the use of quotation marks to enclose phrases. This is a useful technique for making searches more specific and consequently it avoids the generation of long lists of search results.


By using a range of relatively quick and simple techniques, you can enable your users to find the content they need more easily using a search. These techniques can mitigate the two main problems with search: zero results, and too many results.