I'm working in RoboHelp 10. When generating the output, I check "Show Context in Search Results." When someone searches for a term, they get a list of each topic where that term appears, and they see a short summary of the text from that topic. However, the summary includes words from a header on a master page, and it includes the words in an <h1> headline, which is the same as the title of the topic. So the summary is almost useless. Is there a way to exclude content from a master page or a style in the search results? Better still, is there a way to write a separate summary of the topic that will appear instead of the first few words in the topic?
I think I've found the answer to this problem!
First, I added this to the .css file:
Then, I opened the RoboHelp topic in HTML view, and put this in the line right after <body>, before the line that says <?rh-placeholder type="header" ?> :
<p class="invisible">I type the summary of the topic here.</p>
I generated the WebHelp, and it worked! So what it's actually doing is typing the summary in 1-point white type at the top of the page, which no one can see. I tried printing out the page and that worked fine too.
Before I do this on a live project, can anyone think of any negative consequences to this workaround? Would it interfere in any way with any of the other output types? Is there any reason to NOT do it?
The downside I might think of first is that by making this change you are also causing the text that is on the topic itself to become invisible, no? So if you don't want to see the text when viewing the topic itself, why even have it there to begin with? I might just consider removing it using other means than simply hiding it via CSS. But maybe I'm missing something?
Thanks for your reply. I think it might be hard to visualize, so here's what I'm trying to accomplish:
The words in the summary don't have to appear in the topic. However, if they aren't in the topic, RoboHelp makes its own summary by taking the header from the master page -- which is the same for every topic! -- and then the <h1> headline, which is the same as the topic title, and then the first few words of the text of the topic. Then it runs out of room. So the system-generated summary won't give much additional information about what the overall topic is about. If I do it this way, I can say a few words to summarize the topic.
I'm actually a little reluctant to use this workaround, but it appears that RoboHelp does not let you edit what is presented when you select "Show Context in Search Results." If it insists on displaying the first few words of the topic, I figure I'll put my real words in there, and make them invisible. The next-best option, quite frankly, is to uncheck "Show Contents in Search Results," and not show a summary at all.
Hmmm, so let me see if I'm understanding this better.
You have a topic with a Title of "Eggs are good for you" and the first bit of it begins with an explanation about what eggs are. So you generate and you see "Eggs are good for you" along with the first bit of text. But you would prefer the summary actually read differently.
So to overcome this, you added text inside the topic and made certain it was at the very top of the topic and in one point size so it would basically be invisible when viewed or printed. And by doing so, perhaps now the search will present: "Eggs are good for you" along with your inserted (and invisible) text reading something differently. Perhaps: This topic will outline the benefits and reasons you want to eat eggs..
Interesting thought. I'll have to play with that and see what happens... Rick
That's exactly right! To expand on your example, if I did nothing at all, my summary would begin with the words "All About Breakfast Foods," because that's the header on the master page that appears throughout my Web Help. (So those would be the first words of the summary for the egg topic, the bacon topic, the oatmeal topic, etc.) Then it would say "Eggs are good for you." Then it would have a few words of text, such as "Chickens lay eggs..." And then it runs out of room.
What I want is for it to present "Eggs are good for you" as the bold title of the topic, and then a new summary, such as, "Doctors say eating eggs can make you smarter and more handsome." I'm trying to fool RoboHelp into thinking that those are the first words of the topic, because the first words of the topic are what it uses when it generates the summary.
I just want to be sure that if I do this, it won't break something else.
Funny, but even though it's 3 p.m. where I am, I suddenly have a taste for a nice omelet.
Could you not start your topic with a single cell table labelled What's Covered?
We do that not for the purpose you have in mind but has a brief summary so that the reader gets instant confirmation they have landed in the right place.
Another alternative would be an external search tool in place of what is built in. The up side is you have more control and can include / exclude chunks of text and customise in other ways. The downside is it is more work and does not update automatically when you generate the help. The update is easy, just not automatic. If that has some appeal, see the pages on my site about Searching, they describe integrating ZoomSearch into your project.
Having a single-celled table labeled What's Covered is not a bad idea, but it has two limitations that I can think of. First, the words "What's Covered" would be part of every summary, and considering how little space is available, it seems like a waste. Second, it would change the design of the topic. I don't mean to sound overly fussy about it, but once someone gets to a topic, they should be able to tell almost instantly what is being discussed. I'm hard-pressed to think of any newspapers, magazines or web pages that require a paragraph at the top to explain what is being written about, and I would think help screens would be a comparable situation.
I am studying your excellent article about ZoomSearch. (In case others are following this thread, you can read it here: http://www.grainge.org/pages/authoring/zoomsearch/zoomsearch.htm).
Your suggestion about the single-cell table does, however, bring up a related question. Does anyone know of any studies or research that offer a "best practices" approach to online help screens? It seems to me that readability and user-friendliness are just as important for online help as for other printed and online material. Is anyone aware of any design suggestions that can increase the helpfulness of web help screens?
You don't have to have "What's Covered" in the cell. That's just what we do to make the purpose of that section immediately obvious. How little space... We use it for anything from a single line to up to 10 or so lines for complex topics.
Reading through your reply it seems your thinking is based on printed media and I don't think you can compare OLH with all forms of printed media. The nearest is a manual and there I have seen "In This Chapter".
You say people should be able to tell almost instantly what is being discussed and I agree. What better than something short and sharp that states that explicitly? Remember that with OLH people do not work through from start to finish, they skip around following links. A brief section stating what they will find wherever they have landed helps a lot. Our users gave positive feedback when we first added What's Covered.
The problem here is your root purpose is not to make the topic helpful but to make the search better so it is a bit of an abuse of the purpose of What's Covered. I applaud what you are trying to do but at the same time I would point out that what Rh and other tools offer is being used as is. You are creating a lot of work for yourself and only you can decide if that is justified and that you have the time now and ongoing.
As to studies and research, perhaps take a look at Tom Johnson's blog at http://idratherbewriting.com/ He is a Flare user but we will not hold that against him. :-) Most of his blogs are generic anyway and whilst they are long articles, he has written on my subjects.
Keep in mind that whilst some considerations for other online material will be valid for OLH, others will not. The design of online content designed to make you want to buy something could be the very design that will annoy the hell out of you when looking for help.
See www.grainge.org for RoboHelp and Authoring tips
Peter, I continue to appreciate your helpful replies. I will look at the blog you mentioned, and see what information can be gleaned there.
I probably should have done this earlier in the thread, but here is a screen shot of an actual topic from one of my projects:
In this, I have done a search for the word "icon." The summary -- which RoboHelp refers to as the "context" -- is shown in the red circle. When you look in the right-hand pane, you can see where the context is coming from. It's completely logical, but reading the summary as shown would not help a user at all. The bold words "What the icons are for" are perfectly descriptive, but the summary doesn't add anything. In fact, it just confuses things.
If I began the topic with a one-cell table, I could write a quick, insightful summary of the page. I could eliminate the blue banner and the little headline, and in their place, I could write a summary. It means that I'd be modifying what I believe to be a nice design in order to make the search easier. I'm not opposed to that, necessarily, but I find it strange that I have to make a choice. Ideally, I should be able to design the topic any way I like, and edit the context any way I like.
I can't believe that I'm the first person to notice this problem, but in a lengthy search of this forum, I only found it mentioned once, and that was several years ago. Obviously, those who check the "Show Context in Search Results" box when generating web help output have either written great summaries as their first sentence, or they're satisfied with the default.
My idea of writing the summary in 1-point white type is actually similar to your idea of a one-cell table. The only difference is that my 1-point text wouldn't be visible to the user from within the topic. My reservations about the 1-point method are the fact that it is an obvious workaround that forces the system into doing something. And also, what I write will be in the underlying HTML code, and that bothers me. The reason I don't think the summary needs to be visible from within the topic is that once a user finds the topic, the existing text should explain it fully and concisely (if I did a good job as a writer). All the topics in this project are short. Some are only one or two paragraphs. The only place a user might need a summary is when doing the sort of search shown above.
After so much discussion (all very helpful, I might add), it seems that what I'm asking for is new functionality. I'm not sure how to go about asking for that, but the ability to edit the context separately is something that I'd like to see in a future release.
Feature requests are made at http://www.Adobe.com/cfusion/mmform/index.cfm?name=wishform&product=38
ZoomSearch would seem to be your answer right now though as new features are only added with new versions and Rh10 has only just released.
See www.grainge.org for RoboHelp and Authoring tips