This guest blog post was written by Neil Perlin, an internationally known consultant, strategist, trainer, and developer for online content in all forms from traditional online help to mobile.

Part 1 of this series looked at information architecture from an author’s perspective – using MadCap Flare features that users may not be aware of. For example, users won’t know about the concepts of templates or stylesheets; what they will know about is the consistency that comes from authoring with templates and stylesheets. In this post, I’ll look at features that will be more obvious to users, features like search, search filters, and micro content. Users still won’t have the slightest idea how authors used such features but they’ll very clearly see the result.

As with part 1 of this series, I’ll limit the discussion to what I consider to be three major features.

So, what is information architecture?

To recap from part 1, think of it as a structure for creating content, with freedom within that structure. For example, if you build a house, you have the freedom to select light switches within the standards defined by the lighting industry. The difference is that the standards for light switches have been defined for you. You’re selecting the externals – the appearance – but are not setting or modifying the technical standards themselves. For technical communication, however, you’re actually defining the technical standards for your project by using items like templates and stylesheets. This adds complexity to the process but the authoring tool vendors have tried to simplify that process.

To go one step further, think of information architecture as a structure not only for creating content but presenting it as well. When content is well and clearly structured and findable, users are more likely to find the information they’re looking for. This means they’re more likely to use your content rather than ignoring it and calling support.

With that, let’s jump in…

Finding Information – Indexes vs. Searches – Generically

In the early 2000s, online documentation made extensive use of indexes. These were basically the same as printed indexes but online. This was partly because technical communicators knew how to create an index and were largely using printed content as the model for online content. Plus, searching was less powerful than it is now. Since then, there’s been a shift away from indexes and toward search. First, search became more powerful and thus gave better results. Second, and with apologies to my indexer friends, creating an index is tedious and time-consuming but adding search simply consists of telling your authoring tool to enable a pre-defined search feature. The result, at least among those indexers I know, has been a move away from traditional indexing and toward things like defining search synonym lists. And yet…

Search can be more difficult than it first appears and can cause users problems. For example, if I write a topic that talks about a hoagy (the sandwich), I may refer to them as hoagies, period, ignoring the fact that some readers may call them a hero, gyro, torpedo, submarine, grinder, <add your own term…>, etc. So, if a user who calls them grinders does a search for the term that comes naturally – grinders – but I never used that word in the topic, the search will return zero hits. The solution is simple; add grinder (and hero, gyro, etc.) to a list of search synonyms. But this is as tedious and time-consuming as creating an index in the first place.

An index can also train users in a way that search may not. For example, continuing the food example, I can create an index that includes the word hoagy. But I can also include the entry “grinder: also called hoagy”. Following that index link takes users to a topic entitled Hoagy. This serves two purposes. It gives the users the information they were looking for even though they looked for it “incorrectly”. It also tells the users that in this online document, we refer to these things as a hoagy, not a grinder. This reinforces the use of correct terminology more effectively than a search synonym can do. So, ideally, I want both a search feature and an index feature in any online document that I’m reading. I just want someone else to create and maintain that index… 😊

Finding Information – Indexes vs. Searches – In MadCap Flare

Flare has a powerful and easy-to-use indexing feature that suffers from the same drawback as any other such feature – you have to do the work selecting the index terms and synonyms. In contrast, the basic MadCap Flare search feature is pre-defined and pre-enabled. You just generate the output target and the search feature is available for the user. (You can turn the search feature off but I have no idea why any author would ever do so. If you have, please email me to tell me why you did.)

Interestingly, there is an argument for indexing your content even if you never include an actual index in the output – adding index entries can improve the result of a search. I wrote about this in my blog in February of 2018 in a post called “Have You Stopped Indexing Your Flare Projects? Not So Fast…”. You can see the original here.

Search Filters - Generically

One problem with a search, especially when users search a large collection of content, is getting too many hits. The desired hit may be in the first ten but users may not realize that and may waste a lot of time opening each hit on multiple pages. One way to ease this problem – you’ll never eliminate it – is to create search filters that let users narrow the range of their searches to specific categories of topics. They can tell the search feature to search the entire content set or only those topics relating to product line A or B. This can sharply reduce the number of hits. Setting up search filters is mechanical except for the initial definition of the categories, which calls for careful analysis of your content.

Search Filters – In MadCap Flare

As I noted, setting up and invoking search filters in Flare is a mechanical process. The biggest hurdle is to create the category names, or keywords, which Flare calls “concepts”. Once you’ve done that however, it’s a matter of specifying which concept applies to each topic in the content. You then create the filter using those concepts and add the filter feature to the search feature on the skin. Defining the concepts can take some thought but is mechanically easy. For example, if you’re creating an online guide to dogs, each breed might constitute a separate category, flagged with the concept keyword for that category.

To see how search filters look in the output, go to the MadCap Customer Showcase or visit the SimulationX Help Center here. Look at the search field. After about a second, you’ll see a little funnel icon to the left of the search icon. Click the funnel. A dropdown menu will list All Files plus the three subsets – search filters – Libraries, Tutorials, and FAQ, that users can select to narrow a search. Check other entries in the Customer Showcase and you’ll see different search filter icons but their function is the same.

Micro Content – Generically

Although search is obviously useful, it’s often less useful than it might be because the hits are too deeply embedded in larger content. For example, users who search for “tech support phone number” may get a hit on a topic that contains that phone number and a lot of other, irrelevant information, such as other phone numbers. Authors could solve this by creating a tiny, granular topic that just contains the phone number but that could sharply boost the number of topics in a project, complicating the project. A better solution is question-response pairs, with the response consisting solely of the answer to the search question “tech support phone number” – which can be taken from an existing topic – essentially “micro-sized” content.

Micro Content – In MadCap Flare

MadCap Software defines micro content as “text, imagery and/or video content that can be consumed in 10-30 seconds”, i.e. short, concise answers to user questions. MadCap Software added micro content to Flare’s feature set in 2019 and has expanded it since then to the point where micro content can almost serve as a content stream parallel to and equivalent to the standard topic/variable/snippet content stream.


Then there’s responsive design, the subject of past posts and MadWorld presentations…

It should be obvious from this short second post that MadCap Software offers significant support for information architecture. And Flare and Central offer many additional features that further support information architecture even though they’re not information architecture features per se. Given all these features, there’s sufficient power that the inconsistencies of old should no longer plague us. If they’re designed and managed carefully.