Bazel: Enhance documentation search experience

[s-pace]

Description of the problem / feature request:

Hi first of all thank you for your product, we saw it at FOSDEM 2018.

I couldn't help me providing a nice search experience for you good documentation, see below.

Feature requests: what underlying problem are you trying to solve with this feature?

Looking for a precise topic might be tricky and hard sometimes

Congratulations, your search is now ready!
I've successfully configured the underlying crawler and it will now run every 24h.

You're now a few steps away from having it working on your website:

• Copy the following CSS/JS snippets and add them to your page

<!-- at the end of the HEAD -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" />
<!-- at the end of the BODY -->
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
<script type="text/javascript"> docsearch({
  apiKey: '8e0152321e991cc72635d18bfd059bf1',
  indexName: 'bazel',
  inputSelector: '### REPLACE ME ####',
  debug: false // Set debug to true if you want to inspect the dropdown
});
</script>

• Add a search input if you don't have any yet, and update the inputSelector value in the code snippet to a CSS selector that targets your input field.
• Optionally customize the look and feel by following the DocSearch documentation (https://community.algolia.com/docsearch/documentation/)
• You can also check your configuration in the github repo (https://github.com/algolia/docsearch-configs/blob/master/configs/bazel.json). Feel free to open pull requests!

Feel free to get back to us if you have any issues or questions regarding the integration.
We'd also be happy to get your feedback and thoughts about DocSearch - so we can continue to improve it.

Have a nice day :)

[jin]

This looks really nice! @spomorski do you think we can integrate this?

[sergetron]

Let me look into this!

[s-pace]

Feel free to ping me for the integration. You should only need to add an id attribute on your input and then integrate it within the snippet.

We do also provide analytics on the search.

[s-pace]

@spomorski @jin Let me know if you have any question.

In the meanwhile, I have updated your DocSearch index. It is live.

We would be happy to help, give guidance.

Cheers

[s-pace]

I have made a 2 sec bootstrap:
http://bazel-docsearch.surge.sh/

[s-pace]

👋 @spomorski @jin Did you have some time to dig into it? Any feedback?

Happy to PR if you have any instruction.

Have a nice week

[jin]

I really like the demo on the bootstrap site! @spomorski, can we use this?

[sergetron]

Been swamped, sorry. I can look into it this quarter.

On Mon, Apr 16, 2018, 03:42 Jingwen [e-mail] wrote:

I really like the demo on the bootstrap site! @spomorski
https://github.com/spomorski, can we use this?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/bazelbuild/bazel/issues/4600#issuecomment-381508419,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AbdI8nbX8jUmiP0tEfpAt6OdIUyFmkePks5tpEtagaJpZM4R9C6I
.

[sergetron]

Let me take a look at the bootstrap today.

On Mon, Apr 16, 2018, 03:42 Jingwen [e-mail] wrote:

I really like the demo on the bootstrap site! @spomorski
https://github.com/spomorski, can we use this?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/bazelbuild/bazel/issues/4600#issuecomment-381508419,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AbdI8nbX8jUmiP0tEfpAt6OdIUyFmkePks5tpEtagaJpZM4R9C6I
.

[laurentlb]

I see only 5 results with the auto-completion. Is there a way to see all results (like the current search we have)?

[s-pace]

👋 @laurentlb

You can change the number ofhitsPerPage;

<!-- at the end of the HEAD -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" />
<!-- at the end of the BODY -->
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
<script type="text/javascript"> docsearch({
  apiKey: '8e0152321e991cc72635d18bfd059bf1',
  indexName: 'bazel',
  inputSelector: '### REPLACE ME ####',
   algoliaOptions: {
      hitsPerPage: 9,
   },
  debug: false // Set debug to true if you want to inspect the dropdown
});
</script>

If you want to change the Search UI, you can build one thanks to the recommended Search UI InstantSearch. I can help you even I do recommend to use the dropdown one.

[sergetron]

I don't really have the coding experience to implement this, so if anyone
on this thread is willing to do it, please do so by all means! Laurent
brought up a lot of valid points about the site functionality in other
discussions and we do need a SWE to maintain our site.

On Mon, Apr 16, 2018 at 10:19 AM Sylvain Pace [e-mail]
wrote:

👋 @laurentlb https://github.com/laurentlb

You can change the number ofhitsPerPage;

If you want to change the Search UI, you can build one thanks to the
recommended Search UI InstantSearch
https://community.algolia.com/instantsearch.js/. I can help you even I
do recommend to use the dropdown one.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/bazelbuild/bazel/issues/4600#issuecomment-381613940,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AbdI8sk6iYb6O1kDg4jyqp4D5GAnWKLaks5tpKhlgaJpZM4R9C6I
.

[s-pace]

👋 @spomorski

I have made it for you a963098
A quick preview is available here http://bazel-docsearch.surge.sh/

Let me know WDYT

[sergetron]

Wow, that is really, super-nice! Big improvement over our current site. Thank you so much for the implementation. Looks great.

[laurentlb]

To clarify my comment:
When I search "cc_library" on our website, I see all 48 results: https://docs.bazel.build/search.html?cx=012346921571893344015%3Axv_nfgpzbu4&cof=FORID%3A10&ie=UTF-8&q=%22cc_library%22
When I search try the same with your proposed change, I see only 5 results.

So we seem to lose a lot of information (I don't want to change the constant 5, I want a way to list all results).

[s-pace]

@laurentlb You don't miss anything, we only display the 5 most relevant results. We can increase this number if you think it is needed. The search experience is giving you feedback, this is why most of the time you only need the dropdown.

@spomorski Thank you for your feedback. Let me know if you want me to PR it.

[s-pace]

Hi there,

Hope you are doing great.

Do you need some help in order to integrate DocSearch? I would be happy to help and note any of your feedback.

By the way, we do provide the algolia analytics for free for your DocSearch index. Please send me the email addresses of the people you want to grant access to.

Have a nice day,

[philwo]

Hi @s-pace,

thanks again for your continuous effort here. @fweikert and me (Bazel EngProd team) will see that we can enable this on our website as part of reworking our website for Bazel 1.0.

Can you please give access to the index to [email protected] and [email protected]?

One question: Can we tweak the search to return better results for important keywords in Bazel? For example, when I search for "java_binary" I'd expect to land here: https://docs.bazel.build/versions/master/be/java.html#java_binary but that destination doesn't show up in the auto-complete list at all at the moment.

Thanks!

[s-pace]

Hi @philwo

Thank you for your feedback and the details.

Sure:

• @fweikert has already access to the analytics we provide.
• I have granted [email protected]. You will need to choose the DOCSEARCH application from the algolia dashboard (top navbar). The analytics will be available from the analytics tabs from the right hand sidebar.

Before to index it, our engine break down compound words. _ is considered as a separator and is not index. I have updated and deployed the update. You can try it live :)

Feel free to ping if you need any help.

[s-pace]

Live demo, with a typo on purpose:

[laurentlb]

To state again my concerns:

• We get only 5 results (the current Google Search lists all results)
• I don't see the url before clicking on the link
• I cannot open the results in a new tab

When I look for "starlark provider", Google Search gives me the correct link (https://docs.bazel.build/versions/master/skylark/rules.html) as the first result. Algolia doesn't even show it:
https://i.imgur.com/sfjW30g.png

So even if the UI looks great, I feel like it is a regression.

[s-pace]

:wave:

Thank your for sharing your concerns.

We get only 5 results (the current Google Search lists all results)

You can increase the number of displayed result thanks to the option hitsPerPage

I don’t see the url before clicking on the link
I cannot open the results in a new tab

You definitely raise a topic which we're aware of, it will be fixed in an upcoming version.

When I look for “starlark provider”, Google Search gives me the correct link (https://docs.bazel.build/versions/master/skylark/rules.html) as the first result. Algolia doesn’t even show it:

I am a bit confused about this example. We return pages talking about starlark, and containing the word provide. We think these pages are the most relevant.

The page you are referring to do not contains the word starlark. What makes you think this page is more relevant?.
We would be happy to solve this issue by extracting additional content (could be added via meta tags)

So even if the UI looks great, I feel like it is a regression

In addition to the UI, the dropdown introduces a search-as-you-type experience. We think it enables you to have more control over your search usage. User understand the structure of the documentation and correct themselves. We do provide analytics over the search usage. You will be able to understand what your users do not.

[laurentlb]

ok, I don't want to argue about which page should come first (search engines always feel like magic).
If I search only for "provider", I get this: https://i.imgur.com/sbOSYF0.png
In other words, all 5 results point to the same page.

You can increase the number of displayed result thanks to the option hitsPerPage

On https://www.algolia.com/doc/, I see you can show more results. On your site, you have 15 results per page and it's not limited to one page. Also, your website handles well the "open link in new tab".

Once we have that, it's not as important to know which link is shown first (if the user can go through the results).

You definitely raise a topic which we're aware of, it will be fixed in an upcoming version.

Sounds good! Can you ping this thread when it's ready? Thanks!

[laurentlb]

I've played with it locally (thanks for the proof of concept!). It's much nicer when I increase the number of results, and it works quite well in general.

The search results for "providers" is still annoying: https://i.imgur.com/qTDmrjw.png (all 12 results are from the same page). Other searches I've tried are quite good.

[s-pace]

@laurentlb Regarding these requests:

• I don't see the url before clicking on the link
• I cannot open the results in a new tab

The new release is solving it. This is a huge feature now.

[meisterT]

@jin @gregestren @laurentlb is this something you want to do as part of your documentation overhaul?

[laurentlb]

I improved the search integration a while ago, and I believe this is good enough.
When I did some tests, I found that the Google results had a much better ranking.

[s-pace]

We can fine tune the ranking. I do believe the search is smoother with DocSearch. Let us know if you want a PR anytime.

[laurentlb]

I know we can improve things after tweaking, and the UI looks nice, but Google results are good out-of-the-box (and keep working even after changes in the website).

Compare:

• https://bazel.build/search2.html?q=depset (Algolia)
• https://bazel.build/search.html?q=depset

Compare:

• https://bazel.build/search2.html?q=provider (Algolia)
• https://bazel.build/search.html?q=provider

Compare:

• https://bazel.build/search2.html?q=exports_files (Algolia, doesn't even find https://docs.bazel.build/versions/master/be/functions.html#exports_files)
• https://bazel.build/search.html?q=exports_files

In addition to the dubious ranking, you can notice the titles/links are missing. That was working a year ago; I suppose it broke after a change in the structure of the website. On the other side, the Google results don't require any maintenance.

So I'm pretty happy with the current state and I don't plan to make any change.