Required to Expand

Here's something that came up at work that I want to capture on this blog. The issue is finding text in documentation when the searched for text is within an expand / collapse section and that section is collapsed. This is not for a help file in the sense of WebHelp output from RoboHelp or Flare. This is a Confluence site so let me use that as my example.

From https://confluence.atlassian.com/display/CONF55/Confluence+Documentation+Home, enter this text in the search box:

• This text is hidden until you expand the section. 

The first hit is https://confluence.atlassian.com/display/CONF55/Expand+Macro.

Press Ctrl+F. It says there is one match on this page. It is in the “Storage format example” section, right?

Scroll up to the Expand me… link, which is the 3rd line after the title.

Expand that link.

Press Ctrl+F again and enter this text in the page-level search box:

• This text is hidden until you expand the section”

How many hits do you get?

Two hits. Wait, I though there was only one hit so why are there now two hits?

The page-level search doesn’t look inside the collapsed text section!

That’s what is happening with our documentation. The ‘global’ search finds a word (using "jetty" as my example) on the page but you have to expand the section(s) of text (more clicking) in order to find it.

Is there a use case for this scenario? I think so. Consider that a user of the documentation I write at work knows, somewhere in our documentation, they have read about “jetty” but damn, they don’t remember where they read about it or in what context.

Since they don’t know what context the word is used in, the TOC is useless. The user decides to use the Search box – which they know will search the entire site - to search for the word "jetty" with the hope that when they see the search results, they will find the information about it that they need to solve their issue. So, the user clicks Search and the search results tell the user that there is a page with that word on it. When the user gets to that page, the user see the graphic in step 2 below. When the user then searches the page using their browser page-level search functionality (for example, using Firefox) for “jetty” there is not a hit at the page level. This is confusing because the search results just told the user that “jetty” is on this page, but searching at the page level contradicts that information because there is no search result. On the page that the global search results' said had a hit, there are two expandable sections. The user goes to step 3, which is to expand the first section. Again, the user uses the search functionality in Firefox to look for “jetty” and, again, there is not a hit for “jetty” on this page. Within the first expanded text, there is a second section that can be expanded. The user expands that and, again, searches for “jetty” on the page. That is where the user finds it. The issue is that the search results for the entire site tell the user “jetty” is on the page but when the user arrives at the page, the user can’t find the word “jetty” unless they click two more times to expand the collapsed text.

If you wanted to read the above in a step-by-step procedure, it'd look like this.

1. User goes to your documentation site and enters "jetty" in the search box and clicks Search. There is a page that is listed in the search results. User clicks the link to access the page. On the page that was listed in the search results, the word "jetty" is included within a collapsed section of the content. 
• 
2. User presses Ctrl+F and enters "jetty" in the browser specific search. No hits.
• 
3. User expands first section of text. User presses Ctrl+F and enters "jetty" in the browser specific search. No hits.
• 
4. User expands second section of text. User presses Ctrl+F and enters "jetty" in the browser specific search. User is able to see the paragraph that contains "jetty".
• 

So, after the user finds what they want through the search functionality, the user is then required to click additional times to find the text that is within a collapsed section of text.

I do not find the conclusion to be acceptable. I don't want to make the user do more work than is absolutely necessary. I want the user to click the link in the search results (step 1), go to the page, and have step 2 be like this to be the second part of step 4 where the user presses Ctrl+F, enters "jetty" in the browser specific search and is able to see the paragraph that contains "jetty". If I were the user using this documentation that makes me click additional times to find what the search told me was there, I would not be happy.

In a brief survey of the Microsoft online Help for Outlook 2013, I could find an example of where the "global" search of the online Help tells me a word is on a specific page, but after arriving at the specific page, it is within a collapsed section of text. Microsoft does have an "expand / collapse all" link so that is better than expanding multiple sections, but it is still not ideal.

More about this topic as I come across it.

Here’s another example

You are using Acrobat and you get this error message: “Online Help content cannot be displayed. Verify you can launch your web browser and have access to the Internet.” You happen to have a shortcut to http://helpx.adobe.com/acrobat.html on your Desktop because you <sarcasm>never have issues with their products.</s>

You open http://helpx.adobe.com/acrobat.html and you enter “Online Help content cannot be displayed. Verify you can launch your web browser and have access to the Internet” in the search box. You click Search.

You get to a page that lists results: http://www.adobe.com/cfusion/search/index.cfm?cat=support&term=%22Online%20Help%20content%20cannot%20be%20displayed.%20Verify%20you%20can%20launch%20your%20web%20browser%20and%20have%20access%20to%20the%20Internet.%22&loc=en_US&self=1&lr=en_US&site=acrobat_all&product=acrobat

There’s only one hit for this string of text and it’s on this page: http://helpx.adobe.com/acrobat/kb/error-online-help-content-cannot.html

Now, we’ll use our imagination and pretend the following:

1. that the headings on this page (Issue and the Solutions 1 – 4) are hyperlinks that, when clicked, show the user expanded text.
2. that all of these sections are collapsed
3. that the only place on the entire page where the exact text you searched for is in the Solution 3 section.

Thus, if those sections are all collapsed and you press Ctrl+F on this page and search for “Online Help content cannot be displayed. Verify you can launch your web browser and have access to the Internet”, the browser / page specific search would tell you that the text is not on this page.

And that’s the issue! The page-specific search doesn’t look inside collapsed text but the search you used on http://helpx.adobe.com/acrobat.html *DOES* give you results if the text you are looking for exists within the collapsed text.