Any value in indexes for WebHelp or HTML5 outputs?

[rhetoric101]

Common sense tells me that indexes are designed for print outputs, but I'm wondering if anyone still includes them in their WebHelp or HTML5 output.

[Carlsen]

In my opinion Search has replaced the need for an index, and arguably could replace the TOC as well. If your help is context sensitive to the application, then most likely the user gets to where they need to be with a single click. If they open it up outside of the app, how many dig through a complex index or TOC to find what they want? I'd go straight to the search, and often do in my own help system because I don't remember where I put something in the TOC.

However, I still use indexes in my help output. I've held the philosophy that I want to give the user as many points of entry into the help as possible: context sensitivity, TOC, Search, Index, etc. so that the user can find the information however they prefer. But I have no evidence that any of this is necessary, and I suspect that increasingly users just go to the Search.

I also suspect it depends on the age of the user. Older users who at one time were used to using printed documents exclusively (old farts like me) feel warm and fuzzy knowing there is an index available. But younger users don't see the point. They are so used to using Search on the web that they probably don't see the need. At the end of the day, like everything else, it comes down to your audience.

Just my two cents, for whatever its worth.

[NorthEast]

Yes, there is value, because index entries are included in the search (unless you choose the option to exclude them).

So you can use index entries to include alternative terms and phrases that the reader might search for.

You can also use synonyms to include alternative terms, but I find index entries useful when:
- You want to include a phrase (the problem with synonyms is that they can only be single words and not phrases).
- You want to restrict the number of matching topics in the results (synonyms would apply to all topics).

[roboHAL]

Yes. In my opinion there is a big value in the case of HTML5. Specifically, when searching using the index search bar, MadCap filters the list of items using the "contains" logic. This can be extremely useful when you have numerous entries many of which have the same or similar word spelling yet the word (or subset of characters) appears elsewhere in the entire string. For example, suppose you use the index to list all of the fields in your product. Now suppose one of your field names is "Date of Birth" and another is "Birthday Party Location". A user can input "birth" and the list filters to display both of these fields. Using the overall project topic search in the header will find this also, however, the topic titles and abstract (displayed results) can be such that the user still does not know which topic contains the specific phrase they are looking for unless they click into each search result.

[jknasinski]

We are phasing out the use of an index in our WebHelp output and as we move to the "top nav" format there won't be an index. Instead we are improving the search capability in all our projects. We are using concepts and the search filter to give our users better results.

However even if the index is not displayed to the user, creating index entries can help with search engine optimization. Refer to the Flare online help topic on Search Engine Optimization.

Most of our users said they almost never used the index. They went first to the search and second to the table of contents.

[rhetoric101]

So, it looks like there are two benefits to including an index for online output:

* It is a workaround for the limitation of single-word synonyms.
* Index searching, as opposed to primary search, gives users one more avenue to search (and it may even be more direct in some cases).

Does anyone know if it's possible to add an index to HTML5 Top-Nav, or is this just an option for HTML5 Tri-Pane and WebHelp?

[Nita Beck]

Does anyone know if it's possible to add an index to HTML5 Top-Nav, or is this just an option for HTML5 Tri-Pane and WebHelp?

I think it's not possible to add an index to HTML5 Top Nav, if you mean an index mechanism that the user can search and scroll through, as one sees in Tri-pane. I tried experimenting with adding an index "page" to Top Nav output but didn't like the results.

[rhetoric101]

It sounds like a candidate for a product improvement request, either to add phrases to synonyms or to add indexes to top-nav!

[kkelleher]

I think it's not possible to add an index to HTML5 Top Nav, if you mean an index mechanism that the user can search and scroll through, as one sees in Tri-pane. I tried experimenting with adding an index "page" to Top Nav output but didn't like the results.

If I understood the 'say goodbye to tripane' webinar, it's possible to add an index to a TopNav target by inserting an index proxy in your masterpage. I can't vouch for how it look/functions since I haven't worked with it directly. Is this the method you tried, Nita?

Thanks,

Kristen

[Nita Beck]

If I understood the 'say goodbye to tripane' webinar, it's possible to add an index to a TopNav target by inserting an index proxy in your masterpage. I can't vouch for how it look/functions since I haven't worked with it directly. Is this the method you tried, Nita?

Sorry that I didn't explain what I found lacking, and I've since blown away my experiment. But to answer your implied questions, "Yes" and "No". I did use an index proxy, but I didn't put it on the masterpage. Rather, I put it in a topic. Perhaps I should revisit and try it in a masterpage.

[djohnson]

I also wanted to include an "index for index's sake" in my online output and spent some time digging into its guts to get a half-decent format.

I added a separate page to my project with an index proxy; I have style="mc-index-headings: true;" because I like the individual letter headings; this is of course totally optional.

In my main stylesheet, I added the following:

Code: Select all

MadCap|indexProxy { mc-output-support: all; }
p.IndexHeading { display: block; margin: 10px 0 10px 20px; font-size: 1.5em; font-weight: bold; text-align: left; page-break-after: avoid; column-break-after: avoid; }
p.Index1 { margin: 0 0 12px 0; padding: 0;
	mc-reference-initial-separator: '\0a\09';
	mc-reference-separator: '   ';
	white-space: pre-wrap;
}
td.GenIndexText1 a { display: inline-block; background-color: lightgrey; padding: 4px 10px; border-radius: 18px; white-space: nowrap; text-decoration: none; }
td.GenIndexText1 a:hover { background-color: lightblue; color: Black; }

mc-output-support: all allows the index to be displayed online
The p.IndexHeading format is for the letter headings; format as you see fit.
For p.Index1, the mc-reference-initial-separator is a linefeed (\0A) followed by a tab (\09); by setting white-space: pre-wrap, this forces the index links to a new line, indented.
mc-reference-separator is 3 normal spaces; white-space: pre-wrap stops the browser from collapsing these to one space.

I've formatted the actual links (tdGenIndexText1 a) as a bubble, like a tag in many applications. It just breaks up the monotony and gives a clear separation to the links.

I'm only using a one-level index; if you use more, you'll want to format p.Index2, td.GenIndexText2 a, and so on as needed.

index-sample.png