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.

ViziApps Studio’ Logic Builder(TM) – the Continued GUI-izing of Authoring

Authoring tools for new technologies typically start code-heavy but follow the same trajectory over time – tasks that required working in the code can now be handled through a point-and-click GUI. The result?

• Less technical authors can create outputs nearly as powerful as those by more technical authors, so the market expands. (The first online help conference I attended, in 1991, before GUI tools like RoboHelp and Doc-to-Help made an impact of the market, was attended by every online help author that the organizers could find in North America. There were 12 of us. In 1994, after GUI tools had appeared, I gave a speech on help authoring to the STC’s Boston chapter. There were over 100 attendees.)
• Technically-oriented authors, and programmers, can create outputs faster because the GUI simplifies tasks like interface design. Authors can still do these tasks in code if they want to, but they don’t have to.

My example comes from online help, but it applies to another technology that technical communicators can get involved – app development. Technical communicators often don’t see themselves as creating apps, but we didn’t see ourselves as creating online help and web pages in the early 1990s either.

Technical communicators have shied away from apps because of the technical skills required. But just as with online help and the web, new app development tools hide the code behind a friendly GUI, making it more inviting to step into this space. An entire set of app development tools known as “low code/no code”, DIY (Do IT Yourself), or RMAD (Rapid Mobile App Development) tools has appeared in the last few years. (Look for a post about these tools in the near future.)

In this post, I’ll present an example of such GUI-izing in an RMAD tool called ViziApps Studio – www.viziapps.com. (Note – I’m certified in and provide training and development support for Studio.) Studio offers a full suite of predefined actions that you can use to complete a mobile app. Some are simple menu picks, like creating a button that can jump to a specific page in the app. Others support bar code scanning and enable maps and geo-location services. In many cases, these predefined actions may be all you need for your app.

But what if you need more advanced actions that are not predefined. These require JavaScript. The Studio makes it easy to add JavaScript to an app, but you have to know JavaScript in the first place. What if you don’t? That’s where ViziApps’ Logic Builder comes in.

Here's a screen shot of Studio’s old actions dialog box:

It looks straightforward. To jump the user to the previous page, apply that action. To jump the user to a different page, select “Go to page” and specify the name of the target page. No Javascripting.

But what if you want to add a button that, when clicked, clears all entries in all fields on a page? There’s no predefined control for that so you have to write the JavaScript and attach it to the button. Or if you want to perform some arithmetic, like calculating the discount on an invoice? Again, there’s no predefined action for that so you have to, again, write the JavaScript and attach it to the button.

That’s where Logic Builder comes in. Logic Builder lets you add the predefined actions – those that don’t require JavaScript and many of those that do. Here’s the main Logic Builder screen.

Let’s say you want to add a “clear all fields on this page” action to a button. Select the Field Action options. Here’s the result. (The next three images extend off the right hand side of the page. It was the only way to make them large enough to read the screen content.)

Now select the “Clear all the fields on the current page” option. Here’s the result.

Need to specify which page to clear? Select the “Clear all the fields on a page” option and specify the name of the page from a pulldown. No Javascripting.

Want to perform an arithmetic operation? Select Math and Arithmetic Operation. Here’s the result where you can define the operation. Again, no Javascripting.

Will Logic Builder eliminate Javascripting in a project? It depends what you want to do. But Logic Builder will eliminate a lot of it, perhaps all of it. Things may get a bit complicated when you specify field values for some actions – e.g. what’s an array? Or an If-Then-Else? But many business apps may not need these features. If yours does, there’s reference material and training available.

Logic Builder offers many other actions, including:

• Navigation – to move around an app.
• Data management – to retrieve data from or write it to a database.
• Device action – such as making a call or taking a photo.
• Popups – to link to a web page or display an alert.
• Dates and times – to retrieve dates or parts of dates or times.
• Logic – to perform tests on data and take different actions depending on the results.
• Math – to perform mathematical calculations.
• And more.

Each category can be expanded to include new actions, so this feature is extensible to meet future Javascripting needs.

The appearance of Logic Builder and similar GUI authoring features are making it easier for technical communicators to create powerful business apps. App development can become one more skill in your skill set.

NOTE: Logic Builder is in a limited beta release as of February 5, 2018. I’ll post a note when it becomes fully available. 

Logic Builder is a trademark of ViziApps, Inc.

Inexpensive Usability Testing

(Excerpted from my forthcoming book “Writing Effective Online Content Project Specifications”)

We rarely think of doing usability testing for online help or documentation (online content) because, after all, it’s just text. In fact, online content is text, but software forms a big part of it in the navigation, retrievability, and other features. And like any software, it should be reviewed for usability.

What if no group in your company does formal usability testing? Can you do it yourself without spending a lot of money? Yes. The results won’t be statistically significant but they will be useful and inexpensive. How to do this? In brief…

·         Create a prototype of your online content project. It can be a small but fully functional online output or a paper prototype. (If you’re not familiar with paper prototyping, see Paper Prototyping: The Fast and Easy Way to Design and Refine User Interfaces by Carolyn Snyder, published in 2003 and available on Amazon. The book is an excellent introduction to the subject, with additional points on usability in general.)

·         Create several little scenarios with questions whose answers can be found in the prototype. For example, “How many types of fixed asset depreciation are there?” or “What is the specific gravity of tungsten?”

·         Find a small but representative group of test subjects. If you’re testing a product for a general audience, you might set up your test in a conference room and invite people in at random to be test subjects. If your company runs a user conference, that’s also a good place to find subjects.

·         Tell the subjects that you need just fifteen minutes of their time. Offer a small gift (sometimes called swag or “tchotchkes”) as an inducement for them to help. (No pens or coffee cups – both badly overused.) For more impact, tell the subjects you’ll enter them in a raffle for dinner for two at a local restaurant.

·         Give the subjects the scenarios and ask them to find the answers. Watch them but don’t say anything or offer any help. You can tell them to follow the so-called “speak aloud protocol” where they’re free to say what they’re thinking. This may be a bit uncomfortable to hear but it’s the feedback that you want.

      The object is to see if the subjects can navigate through the online content to find the answers to the questions posed in the scenarios and how difficult and frustrating the process was. The results won’t be statistically significant, but may well be very enlightening. That’s what you want.