Searching for partial string in generated (Web)Help

[kevinmcl]

I'm asking this in a general section because I'm not sure if it matters what the output type is (in my case, WebHelp).

How do I persuade the search function - or if it already does, then what do I tell my users/customers to do, in order to search on a partial string?

For example, a command-line command in our application has a flag "-alwaysaskmofn".

Customers would not necessarily know this, and might search on "alwaysask" or even just "always". Currently, those searches don't seem to return instances of "alwaysaskmofn", though I can successfully search for the complete string and get several hits.

Is there some secret-sauce I need to apply?

I tried searching on "search rules" in the Flare Forums and had no joy, so if this has already been answered, I need tips on searching in THIS space, too. (I did use Google and site:forums.madcapsoftware.com after my terms...)

- Kevin

[GregStenhouse]

HTML help as the "advanced search" feature that you can enable in the skin. For other formats (from the help topic "About Search") - it sounds like dotnethelp supports wildcards with SQL server. As for webhelp, I think your only options are (1) create a synonym file, or (2) include your own flavour of search.

[kevinmcl]

Strangely, that's not what I'd really hoped to hear, for my cross-platform help.

Has anybody got any experience with inserting a third-party help function into WebHelp?

Is there a good FLOSS search engine to recommend? I can't get involved in commercial licensing compensation that would raise the cost of the product, and you can imagine the reaction by a cost-conscious manager "How can you call it 'help' if our customers can't even search for what they need to know?"

Does anybody have a better idea for the Help format to distribute for use on Windows, Linux, Solaris, HP-UX, and AIX?


- Kevin

[GregStenhouse]

I've heard people talk about zoom search http://www.wrensoft.com/zoom/ I've personally never used it, but it may work for you.

[GregStenhouse]

Sorry, in reading back I realised you asked for free/open source. A quick google search revealed a few here: http://www.searchtools.com/tools/tools-opensource.html Can't say if they are any good or not though.

[Rona Kwestel]

I'd have hoped to see more responses on this thread, as I just bumped up against the same issue. The only thing I found was that you can download, install, and re-distribute (for free) the Madcap Toolbar (https://www.madcapsoftware.com/downloads/toolbar.aspx), but so far it caused one (recoverable) error in IE8, and it adds yet another toolbar to a potentially already-crowded browser toolbar area. However, since I dismissed that initial error, the toolbar will no longer display automatically, but is available via the View->Toolbars menu and does work when invoked.

So, to use Kevin's example, if you type *always* in the toolbar search box, it will find all topics where the word 'always' appears in any incarnation. (Mind you, this could be a nightmare, as the term 'always' is general enough that the user may get more than they bargained for, and this search facility does not appear to support any sort of filtering.) But all is not yet solved. For topics that use drop-down content, if the search term is embedded in a drop-down, clicking on that topic from the search results will not reveal it. This is inconsistent with the built-in WebHelp search, which does automatically expand drop-downs that contain the search term, and highlight that term. So now the user still can't see where the term shows up and is forced to click on Expand All and then use the browser search (Ctrl-F) to find the partial term. What a mess, all for what should be a simple-to-use yet powerful feature.

One other thought is that Flare v5 has a new In-Topic Toolbar feature, which perhaps allows the help author to embed a more full-featured search button. Unfortunately, we're currently still on Flare 4.2, and it seems like a lot of extra work to have to generate these toolbars for what should be a standard feature.

As an odd aside, if you go to Madcap's website and click on Downloads, the link for the Madcap Toolbar is not shown, but if you use the link I provided above, you'll see that Madcap Toolbar now appears between Flare Skin Gallery and Desktop Backgrounds in the sub-tab bar under Downloads. In fact, I simply could not find a way to get to this download on Madcap's website without finding the topic about it in the Forum and clicking on the specific link. Why is it so hidden?

[NorthEast]

One other thought is that Flare v5 has a new In-Topic Toolbar feature, which perhaps allows the help author to embed a more full-featured search button. Unfortunately, we're currently still on Flare 4.2, and it seems like a lot of extra work to have to generate these toolbars for what should be a standard feature.

On that note, the Topic Toolbar is no different to the WebHelp toolbar, it just allows you to add whatever ToolbarItems have been defined.

Saying that, if you wanted to add your own custom search feature to all your topics, then you could just add it to the master page.

[Rona Kwestel]

Saying that, if you wanted to add your own custom search feature to all your topics, then you could just add it to the master page.

Strangely, that's not what I'd really hoped to hear.

What you're saying is that technical writers are now also supposed to be programmers. While I happen to have a programming background, and agree that script writing ability could be a handy tool for certain special features, I shouldn't have to create my own search utility for a purportedly supported output format by the tool I'm using for that purpose.

I started to wonder if in fact WebHelp search functionality was something outside the control of Flare, but I found the following blog article that clearly indicates that's not the case: http://www.helpscribe.com/2008/10/impro ... ts-in.html. To quote: "MadCap has solved this problem by adding a ranking system to the search results in Flare's browser-based help output." It's plain that Flare does have control over how the WebHelp search feature is implemented, and support for more sophisticated searching should be a high priority. Another article on the same blog had this to say: "Eventually I think help authoring tools will offer a combination of full text search and ranked keyword search to appear in the same help system. (Adobe, MadCap, are you listening?)"

I really do hope that Madcap is listening. Good search capability is critical to the usability of the help output. If users can't find the help topic they need, then the help is not very helpful.

[NorthEast]

What you're saying is that technical writers are now also supposed to be programmers. While I happen to have a programming background, and agree that script writing ability could be a handy tool for certain special features, I shouldn't have to create my own search utility for a purportedly supported output format by the tool I'm using for that purpose.

No, that's not what I'm saying at all. I was just replying to the part I quoted, where you wondered if the Topic Toolbar "perhaps allows the help author to embed a more full-featured search button".

The Topic Toolbar is basically the same as the WebHelp Toolbar, but sits inside the topic - just like the WebHelp toolbar can be placed in HTML Help (in v4 and earlier).

So my point was that the Topic Toolbar wouldn't allow you to embed your own search functionality, but if you wanted to do that (and knew how to), then you could do so by embedding it in the master page.

[Rona Kwestel]

I apologize if I misunderstood, but it seems that you're saying that using the Topic Toolbar will be no different than using the WebHelp toolbar, and so your only choice is to "embed your own search functionality" using the Master Page "if you wanted to do that" and, most importantly, "knew how".

As an aside, I like your "Waiter!" image.

[NorthEast]

apologize if I misunderstood, but it seems that you're saying that using the Topic Toolbar will be no different than using the WebHelp toolbar, and so your only choice is to "embed your own search functionality" using the Master Page "if you wanted to do that" and, most importantly, "knew how".

The idea of embedding your own search functionality is one you suggested in the first place, so I assumed it was a solution you were considering. I just commented that you couldn't use the topic toolbar for that but you could embed it in the master page.

[Rona Kwestel]

Oh, I see what you mean now. But I was thinking more that it might give you a Madcap-developed search option that you could stuff in there, not one you'd have to develop yourself. Alas, that's not the case.

[LTinker68]

You can always submit a feature request at http://www.madcapsoftware.com/bugs/submit.aspx.

[dav_lan]

Within our WebHelp we have quite a number of pages with a title or <h1> that contain a forward slash. For example "Trisolation 3DM/DTM outside". This title is actually a function name in our software so we want to give the users an opportunity to enter verbatum "Trisolation 3DM/DTM outside" in the search box to open the correct topic, however when I paste "Trisolation 3DM/DTM outside" into the search box I get a return of (No topics found). If I replace the forward slash with a space and then re-enter the name "Trisolation 3DM DTM outside" into the search box the correct topic comes up.

How can I overcome this problem and ensure that when the user enters "Trisolation 3DM/DTM outside" into the search box the correct topic opens.

I am using Flare v5.0.1

Regards

John

[forfear]

put it in quotes?
So Webelp searches for a match for the whole term?

[dav_lan]

put it in quotes?
So Webelp searches for a match for the whole term?

Thank you for a quick response.

Yes I have tried putting the whole term in quotes ie "Trisolation 3DM/DTM outside"

Does not like the forward slash

[KevinDAmery]

Odds are it thinks it's a restricted character. I think I would follow Lisa's suggestion and put in a feature request (or bug report, depending on how you feel about it).

[NorthEast]

The forward slash isn't a restricted character, you can search for it.
(Special characters/terms are: " | or and + & not ! ^ ( ) )

However, I did a quick test in WebHelp...

Trisolation 3DM/DTM outside - works (i.e. no quotes), 3DM/DTM is a valid search term.

"Trisolation 3DM/DTM outside" - doesn't work

So clearly something is a bit funny there.

[CJWyckoff]

We have found that using quotes does not help in searching for a phrase. Here are three results when searching in WebHelp for a phrase "install, configure" which I know is present:

• If I put in "install, configure" , I get (No topics found).

• If I put in install, configure with no quotes, I get a number of hits showing "configure" highlighted, but not "install".

• If I put in install configure with no comma, I get a number of hits, showing install, installation, configure, configuration, etc.

None of this solves either problem:

• How can readers find a word or phrase that includes punctuation?

• How can readers find an exact phrase?

I will be filing a bug, since this kind of search functionality is what readers expect.

[NorthEast]

I know a lot of punctuation is effectively ignored inside quotes (commas, semi-colons, colons, brackets) - e.g. "install configure" would find "install, configure". Full-stops (periods), at least, can can be included in searches.

[kevinmcl]

Somebody suggested a synonym file, which is all very fine as long as:

a) you anticipate words that people will use in industries you've never met

b) you live with your customers and so will get the grumblings as soon as they happen

c) you have a really short release cycle or can re-release documents (Help) between product releases.

What really happens is that I have no contact with customers, the instances of failure-of-docs that get reported to me are only the ones that somebody bothered to escalate, and by the time they get to me and I get a fix for that one problem, it's a year later.

That means:

a) the original customer is unhappy - they started out unhappy because they couldn't find what they needed in my help, and they remained unhappy long enough to push the issue far enough that it arrived on my plate, and then it took many, many more months before anything happened (next product release, when my revised WebHelp came out)

b) the silent majority of customers' grumblings never reach me, but they are no less ticked-off about my WebHelp's failure to abide by standards that they've come to know on the web, in software and in other forms of Help.

So yes, I too consider lack of working substring/wildcard search to be a bug and not some wouldn't-that-be-nice "enhancement".

[edit]
And did I mention what happens when the ticked-off customer is a big company or agency that's evaluating our products - against our competitors - for a big contract?

MadCap seems to have lots of time and resources to generate a whole industry of applications and suites (most of which address no need or want of mine), while basic searching with strings and wild-cards seems like an odd thing to leave out of a Help product, even unto the 5.0-th generation. No?

Hey, maybe it already exists in Flare and we just can't find it...


- Kevin

[NorthEast]

Somebody suggested a synonym file, which is all very fine as long as:

a) you anticipate words that people will use in industries you've never met

b) you live with your customers and so will get the grumblings as soon as they happen

c) you have a really short release cycle or can re-release documents (Help) between product releases.

What really happens is that I have no contact with customers, the instances of failure-of-docs that get reported to me are only the ones that somebody bothered to escalate, and by the time they get to me and I get a fix for that one problem, it's a year later.

To be honest, they're really problems of your own making.

I'd say one of the principal tasks of an author is to understand your target audience. So if you don't know your customer's industry terminology, then research it. If you don't meet or have much contact with your customers, then try and encourage ways they can give feedback.

On the other stuff, yep, wildcard searches should be handled.

[Rona Kwestel]

MadCap seems to have lots of time and resources to generate a whole industry of applications and suites (most of which address no need or want of mine), while basic searching with strings and wild-cards seems like an odd thing to leave out of a Help product, even unto the 5.0-th generation. No?

Agreed. And everyone else who agrees should file a bug report. Then maybe we can hope for better in version 6.

[kevinmcl]

[Replying to Dave]
Thank you for the slap in the face, Mother Superior.

Note that ours is not the only company that creates highly configurable, adaptable, products to serve particular industries and niches and then finds out that entirely unanticipated companies and government agencies, etc., come calling. Or our enterprising sales and biz-dev forces apply their imaginations and field smarts to seek out entirely new niches and opportunities as the market evolves. Leverage. Takes place:
a) after the initial fact
b) in ongoing fashion
c) with as few hard-and-fast pre-conceptions as possible.

Also, given that our systems are generally provided as dev/toolkit platforms and are then repackaged for downstream sale by our customers (with their apps), it's no surprise that we get lots of people wanting to adapt our stuff. We add in terminology equivalents and expand our concepts and examples whenever we become aware of new stuff, new directions. But that often/usually happens in rather linear fashion for those of us bound by a one-way flow of time.

Perhaps your direct line to gawd allows you to bypass such evolution and simply be complete-and-right from day one. Congratulations.

- Kevin

[NorthEast]

I just didn't really understand your point about synonyms; it was a useful suggestion that was made, but your problem appeared to be that you didn't know what terms to use for the synonyms.