hmmm. i understand that index entries will open the topic to where they are placed. so because i want index entries to open to the very top of each topic (showing my breadcrumb trail), i entered the index keywords next to each heading. but what happeans is that the viewer is scrolled down a bit, to the heading, so that the user won't even see the breadcrumb trail, and i can't figure out why. (pic enclosed; please scroll to the right to see what i'm referring to.)
any idea why? can i get this to behave the way i want? i tried applying the solution to this post: [url]http://forums.madcapsoftware.com/viewto ... &sk=t&sd=a[/url] (to no avail).
index entries and breadcrumbs
-
nylarising
- Jr. Propeller Head
- Posts: 8
- Joined: Wed Feb 08, 2006 9:47 am
- Location: NJ
index entries and breadcrumbs
You do not have the required permissions to view the files attached to this post.
Re: index entries and breadcrumbs
The only thing I can think of is that you have so many index entries in the heading that the last index entry is a couple of lines down in the code and it's positioning the window to that. If you select an index entry that's listed first in the heading, does the same thing happen, or is the topic returned at the very top?
Lisa
Eagles may soar, but weasels aren't sucked into jet engines.
Warning! Loose nut behind the keyboard.
-
doc_guy
- Propellus Maximus
- Posts: 1979
- Joined: Tue Nov 28, 2006 11:18 am
- Location: Crossroads of the West
- Contact:
Re: index entries and breadcrumbs
This doesn't surprise me. An index entry is added by creating an anchor, which can be inserted at the beginning of your topic, if you choose. However, when the project is built, breadcrumbs are built before any content from the topic is added (consider how your master page is laid out: you have the breadcrumbs first, then the body proxy; the content from the body can't come before the breadcrumbs, because the way the content is laid out on the master page).
If your topic is longer than the window that is displaying it, any link to the anchor will scroll the window down to the anchor point.
I don't think there is a way to point an index topic at a topic, only to an anchor in a topic, so I don't see a way around this behavior.
But the way I see it, this is okay. I mean, users use the index to find key terms, and they want the key term to take them to the exact point in the documentation that talks about that key term. So, when you add index entries, you should add the index term to the exact location where the term is discussed.
Consider the old RH way of inserting index entries to the top of the topic; when your index term was several paragraphs down, when you used a printed target, the index pointed users to the wrong page. The page was the beginning of the topic that discussed the index term, but it wasn't necessarily the paragraph that discussed the index term. (If you are writing long topics and you are inserting you index entries only at the top of all your topics, you're creating the same problem with your Flare output.)
In general, if users want to go to the beginning of a topic, they should use the TOC. If they want to go to the paragraph that discussed a particular term, they should go to the index. The index isn't the TOC, and shouldn't act like the TOC, in my opinion. An index that acts like a TOC isn't a very useful index to me.
If your topic is longer than the window that is displaying it, any link to the anchor will scroll the window down to the anchor point.
I don't think there is a way to point an index topic at a topic, only to an anchor in a topic, so I don't see a way around this behavior.
But the way I see it, this is okay. I mean, users use the index to find key terms, and they want the key term to take them to the exact point in the documentation that talks about that key term. So, when you add index entries, you should add the index term to the exact location where the term is discussed.
Consider the old RH way of inserting index entries to the top of the topic; when your index term was several paragraphs down, when you used a printed target, the index pointed users to the wrong page. The page was the beginning of the topic that discussed the index term, but it wasn't necessarily the paragraph that discussed the index term. (If you are writing long topics and you are inserting you index entries only at the top of all your topics, you're creating the same problem with your Flare output.)
In general, if users want to go to the beginning of a topic, they should use the TOC. If they want to go to the paragraph that discussed a particular term, they should go to the index. The index isn't the TOC, and shouldn't act like the TOC, in my opinion. An index that acts like a TOC isn't a very useful index to me.
-
nylarising
- Jr. Propeller Head
- Posts: 8
- Joined: Wed Feb 08, 2006 9:47 am
- Location: NJ
Re: index entries and breadcrumbs
Thanks Lisa and Paul.
Paul, your explanation makes sense with the behavior because all of my index entries are at the very top.
Paul, your explanation makes sense with the behavior because all of my index entries are at the very top.
-
doc_guy
- Propellus Maximus
- Posts: 1979
- Joined: Tue Nov 28, 2006 11:18 am
- Location: Crossroads of the West
- Contact:
Re: index entries and breadcrumbs
No problem.
You may want to consider how you are inserting index entries, because especially if your topics are long, you might be doing your users more of a favor if the index entries take them right to the term they are looking for, or right to the section where that info is discussed, especially if you are using a printed target.
If the index entry relates to an entire section, then (I think) you want to put the index entry in the heading that relates to the section, so that in the printed output the index gives you a page range, not just a page number.
IE:
topics, creating 56-58
That is new in Flare 4, and I'm pretty sure it happens when you insert the index reference into the heading.
You may want to consider how you are inserting index entries, because especially if your topics are long, you might be doing your users more of a favor if the index entries take them right to the term they are looking for, or right to the section where that info is discussed, especially if you are using a printed target.
If the index entry relates to an entire section, then (I think) you want to put the index entry in the heading that relates to the section, so that in the printed output the index gives you a page range, not just a page number.
IE:
topics, creating 56-58
That is new in Flare 4, and I'm pretty sure it happens when you insert the index reference into the heading.
-
dynamite rabbit
- Jr. Propeller Head
- Posts: 4
- Joined: Fri Aug 29, 2008 8:35 am
Re: index entries and breadcrumbs
I just wanted to say thank you to nylarising for the post. I encountered a similar issue, and the link you gave (http://forums.madcapsoftware.com/viewto ... &sk=t&sd=a[/url]) seems to have fixed my issue.
I want most of my index entries to link to the topic heading because my topics are the more typical, short topics. I'd really like the index entries to behave as you describe (so that user is jumped to the topic heading but can also see the breadcrumbs--even see the banner image would be nice too). But until I applied the fix to the .js file, I was unable to even get my index entries to jump to the topic heading without a huge amount of unwanted white space being added just before the heading title.
All the replies to this post helped me figure out the issue and understand the workings better--thanks to all.
I thought I'd mention too that while I do see some uses for the ability to link from an index entry to the center of a paragraph (or to various parts of a topic if the topic is exceedingly long), I think that technique should be used sparingly in typical help systems (or at least those with with small topics that are well modularized and tightly integrated with themselves and the index entries). Most likely, the user, when jumped to mid-topic, will need to get the context anyway and will scroll up. Very few users (at least in our tests) use the TOC to navigate. They tend to use the index or search first, then give up in the doc. Not to say good effort shouldn't go toward building a quality TOC--just saying not to rely on it. We also don't index every instance of a term, mainly due to time constraints and displeasure with the results of the auto-index-builders that do that. But we definitely use the mid-topic jumps in our longer topics.
I want most of my index entries to link to the topic heading because my topics are the more typical, short topics. I'd really like the index entries to behave as you describe (so that user is jumped to the topic heading but can also see the breadcrumbs--even see the banner image would be nice too). But until I applied the fix to the .js file, I was unable to even get my index entries to jump to the topic heading without a huge amount of unwanted white space being added just before the heading title.
All the replies to this post helped me figure out the issue and understand the workings better--thanks to all.
I thought I'd mention too that while I do see some uses for the ability to link from an index entry to the center of a paragraph (or to various parts of a topic if the topic is exceedingly long), I think that technique should be used sparingly in typical help systems (or at least those with with small topics that are well modularized and tightly integrated with themselves and the index entries). Most likely, the user, when jumped to mid-topic, will need to get the context anyway and will scroll up. Very few users (at least in our tests) use the TOC to navigate. They tend to use the index or search first, then give up in the doc. Not to say good effort shouldn't go toward building a quality TOC--just saying not to rely on it. We also don't index every instance of a term, mainly due to time constraints and displeasure with the results of the auto-index-builders that do that. But we definitely use the mid-topic jumps in our longer topics.