Wednesday, May 9, 2018

A Review of MadCap Flare 2018

MadCap released Flare 2018 last week. In this post, I’ll look at several of the new features that I think are most useful or have the most potential.

Side Navigation Output

The tri-pane skin has existed since 1995 and works perfectly well but it screams “online help”. MadCap’s Top Navigation, or topnav, skin, introduced several years ago, added a more webby look to Flare targets. However, topnav has some limitations compared to the tripane, primarily the fact that it’s not good for targets with long or complex TOCs.

Topnav displays the level 1 TOC heads in the upper pane so having a lot of level 1 heads means that the upper pane may use a lot of space, reducing the space available for content in the lower pane. See the image below for an (extreme) example of how the topnav uses the space in the upper pane.


Reducing the blank space on the left and right sides of the upper pane will reduce the number of lines that the TOC needs. But a long or complex TOC may still need this much space.

The next image shows what happens if the user hovers over one of the headings, in this case “Firewall Properties”.


Again, it can be hard to fit long or complex TOCs into this structure. The tripane eliminates this problem but at the cost of an old-style look and some codes that could cause trouble under HTML5. MadCap’s solution was to create a side navigation version of topnav, as shown below, first collapsed.


And then expanded, below…


It’s showing the same TOC as the topnav example, but TOC length is no longer an issue since the TOC pane can scroll.

Be aware that this skin, like topnav, assumes that the primary navigation for the target is the TOC and search. No index.

In summary, I think this skin is exactly what we’ve needed to offset topnav’s TOC space limitations and I expect it to see wide use.

Project Analysis

MadCap has offered a somewhat tangled set of project analysis options for years – a built-in report generator and a related file tag feature, a Project Analysis option (View > Project Analysis), and the separate Analyzer product.

The report generator and Analyzer product are similar; both offer 120+ reports on broken links, snippet suggestions, undefined styles, and so on. The main difference is that the report generator just creates the reports whereas the Analyzer product can actively help you act on them. Flare has also offered a little subset of the Analyzer under its Project Analysis option (View > Project Analysis).

In Flare 2018, MadCap appears to be taking steps to streamline all these options. The report generator and file tags features are still available but MadCap has added the core of the Analyzer product to Flare itself. In other words, we’ve gone from this in pre-2018 versions.


To this is Flare 2018 (with just one of the menus expanded and 44 reports in total). It’s not the full Analyzer but it’s a good start.


In summary, this should go a long way toward strengthening the analysis and management aspects of any Flare project.

Find Elements

Find Elements is a seemingly innocuous little feature that should come in handy if you have to clean up the code in legacy files. It’s available from the Home ribbon’s Find and Replace group and looks like this when first opened.


The Find What field offers the following options.



The results appear in a Find Results pane, typically at the bottom of the screen.

In summary, the most useful options, in my opinion, are inline styles, if you have to clean up legacy files, and MadCap, if you’re using Flare to create HTML files for use outside Flare, such as for a wiki, and have to find and remove Flare-specific tags in the output HTML files.

Other Interesting Features

Two in particular…

  • Review Workflow with MadCap Central – This new feature adds a new twist to your review workflows. If you’re a Contributor user, you’ve been able to solicit comments and new content from SMEs for years but you had to buy Contributor to do so. Now, if you’re a Central user, there’s no need to buy Contributor. Instead, you can add your SMEs to the review workflow through Central, in the cloud. Some of the benefits include multi-reviewer workflows, a simplified review-only interface, and change tracking.
  • Elasticsearch – This new feature adds a third search engine option to your projects in addition to MadCap’s own search and Google Search. My experience is that most users happily go for the MadCap search but a small number are looking for alternatives. For a comparison of the three types, see http://help.madcapsoftware.com/flare2018/Content/Flare/Targets/More/Setting-Up-Search-Engine.htm.

Summary

What I like:

  • How the Side Navigation Output allows Flare authors with long or complex TOCs to get the same benefits as topnav but without the space constraints.
  • How the Analysis feature adds tremendous project management and analysis control natively.
  • How the Find Elements feature helps authors look at the internals of their projects.
  • How the Central-based workflow adds a new option to Flare and continues what appears to be MadCap’s move into the cloud.

In my opinion, these features, especially the Side Navigation Output, make Flare 2018 a solid release that’s worth upgrading to.


Monday, February 19, 2018

Have You Stopped Indexing Your Flare Projects? Not So Fast…



Many Flare authors no longer create indexes for their targets, instead relying on the search feature. It makes sense. Most authors find indexing tedious, so the search feature is a simple and widely accepted alternative. And if you use TopNav skins for your targets, there’s no index option anyway. So, you can just abandon indexing entirely, right?

You can, but there are two arguments for creating an index, even if you use TopNav skins.

Improving Search Ranking

Indexing seems to have nothing to do with search, but it can actually make topics found by search show up higher in a search results list and thus be more visible. For example, the screen below shows the result of a search for “FTP Site”. The desired topic, called “Neil’s FTP Site,” has no index entries assigned to it. It shows up in position 5.


I then add the index entry “FTP site” to the topic, regenerate the target, and re-run the search. The topic now shows up in position 2.


Why? When creating the list of search results, Flare assigns different weights to keywords depending on where they occur in a topic. (See “Ranking Search Results” in the help.) Specifically, it weights an index keyword in a topic as if that keyword is a search keyword in a level 4 heading. It’s hard to say exactly what to expect here because topics are so different but, as a general rule, the more index keywords you apply the better your search results. Try it with a topic in your Flare project that users often search for and see if it makes a difference.

Improving Search Synonyms

Adding index entries may let you fix some search synonym issues. This can be a somewhat tangled issue so follow me.

Let’s say that one of your topics describes subs (the sandwich). However, in Philadelphia, subs are called hoagies. But you, the author, being from Boston, never used the word hoagie in the topic. The result? Users who search for “hoagie” get zero hits.

You can fix this by creating a search synonyms file (File > New > Synonyms) and adding a group synonym where “sub=hoagie=torpedo=” and so on. Now, when users search for hoagie, they’ll get the Subs topic. Problem solved?

Perhaps. Users who search for “hoagie” but find “sub” are likely to do one of two things. If you have lots of credibility with your users, they may infer that a hoagie is the same thing as a sub. More likely, they’ll think the index entry was misdirected and the credibility of your material will drop a bit.

The solution is to change the wording of the synonym to make it clear that it is a synonym, like changing the synonym to “hoagie, aka sub”. However, the synonym editor only accepts single-word entries. Now what?

There are two solutions, one that works by using the meta-description feature but doesn’t involve index entries at all, and a speculative solution that does involve index entries.

Meta-Description Solution

The first solution is to add the synonyms in the topic’s meta-description (in the Topic Properties tab of a topic’s Properties dialog box, shown below.


In the Description field, you can enter a description of the topic that displays when users see the topic in the search results list. If I enter the synonyms in the Description field as “Also called grinder, hoagie, or torpedo,” here’s what the user will see in the search results list.

It’s not as efficient as seeing the full synonym in the search highlight but it does the job.

Speculative Solution

This involves creating the multi-word synonyms as index entries. Go to the topic for which you want to add synonyms, like the subs topic, and press F9 to open the Index window. Enter the multi-word synonyms, one per line. For example, for the subs topic, you might add the synonyms “hoagie, aka sub” and “torpedo, aka sub”. If users then search for hoagie, the browser will return the subs topic as the hit. The problem is that the search results screen looks like this.


The search report shows only what the users type in the search field. The complete synonym is “hoagie, aka sub” but you don’t want users to have to type that whole entry or expect them to. You want them to just type “hoagie”, run the search, and see a report that says “Your search for “hoagie, aka sub” returned 1 result(s).” that reinforces the idea that a hoagie is the same thing as a sub.

The problem is that, as of Flare 2017 r3, the search report only shows what the user typed in the search field. It doesn’t list the complete search term. I have put in a feature request to make the search report list the entire entry but there’s no way to tell whether MadCap will add this feature or when. So, you’d be adding these index synonyms on speculation that MadCap might add the feature.

Summary

Indexing is increasingly seen as a dying feature as more and more Flare authors default to using search. But there are some good reasons for continuing to add index entries, especially if you want to increase the findability of certain topics. Indexing may be old but it’s far from dead.