Improve presentation of search results about docs HOT 17 CLOSED

@jseldess agreed. Not mandatory for beta, but I'd like this done sooner than later. Should I put it on DivisionOf's radar?

from docs.

@jess-edwards: Yes, it'd be good to have them come up with a design. But if I understand right, we might need to change the search utility we use in order to control the look/feel of the results page. Ben mentions some options in PR #62.

from docs.

@jseldess Sounds good. I'll bring this up with DO once the website has launched.

from docs.

@jseldess @bdarnell @mjibson

I have a big concern that the current search implementation navigates you away from the website. Can that be fixed ASAP - preferably before docs launches?

from docs.

@jess-edwards, based on what @bdarnell said in PR #62, I think we'll have to move to Google's Custom Search Engine to be able to control the look and feel of the search results page.

There's a free version, but ads will show up. If we don't want ads (I'd prefer we exclude them), we'll have to pay: $100/year for 20,000 searches, $250/year for 50,000 searches, etc. Not sure what volume to expect, but we could probably start with the lowest.

@bdarnell, @spencerkimball: Should we just go with the lowest paid option? Or would you rather we look for a free alternative without ads, avoiding client-side search features for the reasons @mjibson mentions in PR #62?

from docs.

@jseldess paying for it sounds good to me. We can start with the $100 version and scale up accordingly. $100 seems pretty trivial for a great, ad-free product.

from docs.

Cool. I'll make sure this gets done for beta.

from docs.

@jess-edwards What exactly do you mean by "navigates you away from the website"? A google custom search engine is also "away from our website", although we retain some control over the presentation. I'm fine with paying for it if it works, but want to make sure it will actually solve the problem before we move further down this path.

If a CSE doesn't fit our needs, then I'd like to push back on doing anything about this pre-beta. The other solutions are a significant amount of work. (I think a client-side search is our next best bet. It's far from ideal but we're not big enough yet that the limitations are dealbreakers)

from docs.

I think the solution at http://www.aerospike.com/docs/ is exactly what we should do. It uses google to perform the search using a javascript request and displays the results in the documentation chrome. I think that'll meet everyone's requirements, and may not be too hard to do.

from docs.

@bdarnell I've attached screenshots for what I meant re: navigating away from our site. The first screenshot is what happens in our docs when you enter something into the search box. You leave the confines of our docs site and enter a google search window.

The second screenshot is how the search behaves happens when you enter something into aerospike's search box. The google search window is embedded within aerospike's docs site.

@mjibson Any idea how they did it?

from docs.

https://cse.google.com/cse/publicurl?cx=007743160730008282920:eqnepufhimm

I created a link to a custom search engine over the cockroach docs with ads.

They do offer an option to add this to your site through code.

On Thu, Mar 3, 2016 at 9:46 AM jess-edwards [email protected]
wrote:

@bdarnell https://github.com/bdarnell I've attached screenshots for
what I meant re: navigating away from our site. The first screenshot is
what happens in our docs when you enter something into the search box. You
leave the confines of our docs site and enter a google search window.

The second screenshot is how the search behaves happens when you enter
something into aerospike's search box. The google search window is embedded
within aerospike's docs site.

@mjibson https://github.com/mjibson Any idea how they did it?

[image: screen shot 2016-03-03 at 9 43 10 am]
https://cloud.githubusercontent.com/assets/6042450/13497637/7d564c34-e124-11e5-87b8-0e70ed1d40ec.png
[image: screen shot 2016-03-03 at 9 42 53 am]
https://cloud.githubusercontent.com/assets/6042450/13497638/7d5e6220-e124-11e5-9a1c-02f0f980544a.png

—
Reply to this email directly or view it on GitHub
#72 (comment).

from docs.

And we do go this path we should definitely turn off the ads. They are a
very big distraction from the content.

On Thu, Mar 3, 2016 at 10:01 AM Vivek Menezes [email protected]
wrote:

https://cse.google.com/cse/publicurl?cx=007743160730008282920:eqnepufhimm

I created a link to a custom search engine over the cockroach docs with
ads.

They do offer an option to add this to your site through code.

On Thu, Mar 3, 2016 at 9:46 AM jess-edwards [email protected]
wrote:

@bdarnell https://github.com/bdarnell I've attached screenshots for
what I meant re: navigating away from our site. The first screenshot is
what happens in our docs when you enter something into the search box. You
leave the confines of our docs site and enter a google search window.

The second screenshot is how the search behaves happens when you enter
something into aerospike's search box. The google search window is embedded
within aerospike's docs site.

@mjibson https://github.com/mjibson Any idea how they did it?

[image: screen shot 2016-03-03 at 9 43 10 am]
https://cloud.githubusercontent.com/assets/6042450/13497637/7d564c34-e124-11e5-87b8-0e70ed1d40ec.png
[image: screen shot 2016-03-03 at 9 42 53 am]
https://cloud.githubusercontent.com/assets/6042450/13497638/7d5e6220-e124-11e5-9a1c-02f0f980544a.png

—
Reply to this email directly or view it on GitHub
#72 (comment).

from docs.

@jess-edwards they are using the CSE API. I will work on a demo for this to see how feasible it is. I don't think it will be too difficult.

from docs.

So I purchased a year of custom google search for $100, plugged the custom search ID and api key into the js, and now we have search that stays in our docs site. Just go to cockroachlabs.com/docs and search to check it out. You might need to clear your cache (I did).

The h1 title of the page is only sometimes showing up in the search results. Anyone have any ideas about how we could improve that?

from docs.

The h1 "title" doesn't officially matter. The official HTML title of a page like https://www.cockroachlabs.com/docs/update.html is "Docs | Cockroach Labs". This is coming from _includes/head.html where the <title> tag always says "Docs". I think we just need to replace "Docs" with something like {{ page.title }} | {{ site.site_title }}. Note that it it will take some time for any changes to be reflected in the search results, but you can test changes here by looking at the title that is shown on your browser tab.

from docs.

Nice...search results are fast and look good.

On Mon, Mar 7, 2016 at 9:53 PM, jseldess [email protected] wrote:

So I purchased a year of custom google search for $100, plugged the custom
search ID and api key into the js, and now we have search that stays in our
docs site. Just go to cockroachlabs.com/docs and search to check it out.
You might need to clear your cache (I did).

The h1 title of the page is only sometimes showing up in the search
results. Anyone have any ideas about how we could improve that?

—
Reply to this email directly or view it on GitHub
#72 (comment).

from docs.

Thanks, @spencerkimball and @bdarnell.

Ben, I just updated _includes/head.html as you suggest. I think it should be working now. Please check PR #104.

from docs.