19 Replies Latest reply on Aug 25, 2017 1:27 AM by Peter Grainge

    Editing context in search results

    newleaf1124

      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?

        • 1. Re: Editing context in search results
          newleaf1124 Level 1

          I think I've found the answer to this problem!

           

          First, I added this to the .css file:

           

           

          p.invisible {

          font-size: 1pt;

          color: #ffffff;

          float: none;

          margin-top: 0px;

          margin-bottom: 0pt;

          }

           

           

          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? 

          • 2. Re: Editing context in search results
            Captiv8r Adobe Community Professional & MVP

            Hi there

             

            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?

             

            Cheers... Rick

            • 3. Re: Editing context in search results
              newleaf1124 Level 1

              Thanks for your reply.  I think it might be hard to visualize, so here's what I'm trying to accomplish:

               

              summary.gif

              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.

              • 4. Re: Editing context in search results
                Captiv8r Adobe Community Professional & MVP

                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

                • 5. Re: Editing context in search results
                  newleaf1124 Level 1

                  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.  

                  • 6. Re: Editing context in search results
                    Peter Grainge Adobe Community Professional

                    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.

                    • 7. Re: Editing context in search results
                      newleaf1124 Level 1

                      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?

                      • 8. Re: Editing context in search results
                        Peter Grainge Adobe Community Professional

                        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

                         

                         

                        @petergrainge

                        • 9. Re: Editing context in search results
                          newleaf1124 Level 1

                          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:

                           

                          index.png

                           

                          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. 

                          • 10. Re: Editing context in search results
                            Peter Grainge Adobe Community Professional

                            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

                             

                             

                            @petergrainge

                            • 11. Re: Editing context in search results
                              Captiv8r Adobe Community Professional & MVP

                              Hi all

                               

                              I could easily see this manifesting in the following way:

                               

                              Add an area named "Context" to the properties panel for a topic. It might look as follows:

                               

                              tmp1.PNG

                              Cheers... Rick

                              • 12. Re: Editing context in search results
                                ToddO

                                Hello. Yes, hugely annoying. Also calling 60 characters of context a "default" is misleading given that you cannot change it :-}} What did you end up doing? I liked your invisible text idea.....did it work? I also liked your suggest of adding Context as a property of the Topic.

                                • 13. Re: Editing context in search results
                                  NickShears

                                  Adobe seem to have implemented something akin to your suggestion, Rick.

                                  In RoboHelp 2015:

                                  1. Add the context as the 'Comment' in the topic properties. (Annoyingly, the latter now seems to be accessible only by right-clicking the topic, the toolbar toolbar button has gone.)

                                  2. When generating Webhelp output, select "Use Topic Comment as Search Context" on the Search tab.

                                  3. your custom context is used instead of the beginning of the topic.

                                   

                                  (If only I could find a way to do something equivalent for PDFs included in the search results.)

                                  • 14. Re: Editing context in search results
                                    Faeneth Level 1

                                    Hi,

                                     

                                    I'm running into a similar problem. I'm using RoboHelp 2017, so the option to use topic comment as search context is already available. However, I can't seem to figure out where I can add this topic comment.

                                     

                                    When I open the properties for a TOC entry, I have a field "Comment" in the Advanced tab. However, the comment I enter there is not used for search context in the output.

                                    When I open the properties for a topic itself (from the Project Manager pod), I don't see any option to enter a comment or topic comment.

                                     

                                    Can somebody help with this? Thanks.

                                    • 15. Re: Editing context in search results
                                      Peter Grainge Adobe Community Professional

                                      It's in Topic Properties.

                                       

                                      Peter Grainge

                                      www.grainge.org

                                      @petergrainge

                                      • 16. Re: Editing context in search results
                                        NickShears Level 1

                                        As Peter Grainge says, it's in the Topic Properties.

                                        It's the "Comment" field on the "Status" tab.

                                        (I'd love to know why someone thought that was an appropriate place.)

                                        rhtopic-properties-comments.png

                                        • 17. Re: Editing context in search results
                                          Captiv8r Adobe Community Professional & MVP

                                          Hi there

                                           

                                          My own educated guess based on observation would be to speculate that since this field has been present for a long while in RoboHelp that they simply found a way to repurpose it and make it useful with a minimal amount of effort.

                                           

                                          That's my theory and I'm sticking to it! LOL

                                           

                                          Cheers... Rick

                                          • 18. Re: Editing context in search results
                                            NickShears Level 1

                                            That makes sense, Rick.

                                            I used to use it to note the most reason change in a topic, and its release no.

                                            In new projects I use it for search context.

                                             

                                            Cheers,

                                            Nick (who loves how we're still contributing to a 4.5-year-old thread.)

                                            • 19. Re: Editing context in search results
                                              Peter Grainge Adobe Community Professional

                                              Another method with update stuff is to the content and then use a build expression to exclude it from release outputs. It is left in so testers etc can see what has changed.

                                               

                                              Just make sure the comments are nice in case someone else screws up the release!

                                               


                                              See www.grainge.org for RoboHelp and Authoring information

                                               

                                               

                                              @petergrainge