Improve search experience

[delucis]

Have experience with or interested in learning more about DocSearch? Help us out and take a look at one of these tasks!

• Increase the number of results returned by DocSearch (currently maxes out at 5). Maybe with the pagination parameter passed to searchParameters?

  What’s the number of results we want? Should it paginate to include as many as possible (if that’s possible)?

• Improve the snippet for each result so there’s clearer context around what you might be clicking on. (Awaiting more feedback from @sarah11918 on what we’d like there.)

• Break up search results into categories: docs vs tutorial

• Look into duplicate results. Here’s an example where results show up twice, one always linking to the page’s #article ID.

  

  22/11/3 — This doesn’t seem to be happening anymore?

• Look into items in the integration nav component ranking in search, e.g. Docs "search stats" investigation #2042 (comment)

  Update (18 Nov 2022): This should be resolved when the Algolia crawler next runs — I updated the crawler to strip the navigation component from the page before extracting records.

[sarah11918]

I owe you comments here, and I will provide!

1. My MAIN gripe is the number of items shown (which may just be a configuration setting?) I'm never convinced it's showing me all the hits for a search term, and I've seen it prioritize multiple hits on the same page rather than surfacing another page where something might be.

That almost makes it hard to evaluate further, because I don't know what I'm missing! So, I think even just your three items above would go QUITE a long way to improving this.

[delucis]

One more focused thing you could look at would be the second bullet point. In a dream world where anything is possible, what contextual information would you love to see alongside a search result to help a user know that that’s the result for them?

[sarah11918]

Let's see... to throw some wild ideas out there

First set of results: the word is a hit for page title/file name
(So, if you just want to hit a major page for your result, you don't have to read anything in a snippet, just go.)

Second group of results: the word is in a heading
(Similarly, if you see a relevant heading, you probably don't care much about extra context displayed, just go.)

Otherwise, hits for the word in text display:

• Page name (file/route or title?)
• Section heading in which the text occurs (might restrict this to a L1 to L3 heading, otherwise it might be too specific to give a better context?)
• 2 - 3 lines surrounding the word (word in sentence context)
• Number of times the word appears on that page? (this would give a kind of "heat map")

I don't even know whether categorizing like above is possible, but if so, it might be interesting to also highlight when the word appears in a code sample?

Does that give you some ideas to work with? :)

[delucis]

This is super helpful — thanks Sarah!

[sarah11918]

Also adding, it constantly comes up that people click on our language picker instead of the search bar when searching!

[sarah11918]

@mayank99 If you are interested in contributing to a less-confusing design, this would be the place to say so! (Just to make sure we get all the search stuff discussed here, and form and function work together.)

[mayank99]

@mayank99 If you are interested in contributing to a less-confusing design, this would be the place to say so!

@sarah11918 Yeah, if you have a general idea of what you would like the new design to look like, I can implement it and submit a PR.

I was thinking of doing three things:

• remove the border from the language select
• make the language select smaller
  • the longest language name is Português do Brasil. maybe we can remove "do Brasil" from it? truncate? abbreviate to "BR"?
• make the search field slightly longer

[delucis]

I wonder if the key issue is actually the field width like @mayank99 suggests in the final bullet point — certain expectations between how wide a search box is vs a drop-down. Here’s a simple tweak on that front (would truncate Portuguese but we can do that with text-overflow: ellipsis; overflow: hidden for reasonably nice styling):

I don’t know if we also think the styling is an issue. Flipping the styling these each have currently would look like this:

[delucis]

Oh and I guess the other thing to consider is something like shape. Round ends for search boxes are not uncommon:

(In this case I might think about restyling the / shortcut indicator)

[yanthomasdev]

make the language select smaller
the longest language name is Português do Brasil. maybe we can remove "do Brasil" from it? truncate? abbreviate to "BR"?

I believe using the language's BCP flag is the best approach here. It's short enough and avoids ambiguity. For example, removing "do Brasil" would make people believe it's European Portuguese instead.

Thanks for the willingness to tackle this @mayank99, you're awesome!

[delucis]

I'm not sure about using the BCP tags as I don't know how familiar everyone is with those. For some of our languages that would also mean a label in a different alphabet from that language's main alphabet. I think visually truncating the label for Portuguese but otherwise leaving the content unchanged is ok: "Português d…"

[mayank99]

I'm not sure about using the BCP tags as I don't know how familiar everyone is with those. For some of our languages that would also mean a label in a different alphabet from that language's main alphabet. I think visually truncating the label for Portuguese but otherwise leaving the content unchanged is ok: "Português d…"

Agree with this. Languages <=> Flags is not a 1:1 mapping. Plus, with truncation, the user can still see the full name if they open the select menu.

[sarah11918]

Just chiming in to say that I like both the change in field with, and the pill/rounded idea for the search bar!

[surjithctly]

Hey everyone,

I’m one of the people who always clicks the language instead of search.

I proposed a solution for that in #1972 but I understand it will be a bad choice for removing the text from the language picker.

Now we are left with two options:

1. Move the search bar to left and language picker to the right. Make the select box with auto based on the text size. So english width will be smaller.

2. Move the search to the center instead. Many documentation sites uses the center search thus its familiar.

Thoughts?

[delucis]

There’s only one thing outstanding in this issue:

Improve the snippet for each result so there’s clearer context around what you might be clicking on.

From my research, there’s not much we can do here as we’re constrained by the result data we get back from Algolia. I’m personally feeling pretty good with the position we’re in now, so I’m going to close this as done and we can open new issues for any search questions we run into in the future.