search UI redux

[devoncarew]

@jcollins-g, @srawlins - I'd like to get your thoughts on a proposal for a redux of the in-page search UI. This might address a few of the findings of the recent user study (though would not address all).

• increase the amount of context info we show per search item (each item becomes 2 lines tall)
• show results in a popup, scrolling list; show a max number of elements (it's not useful to see 1000 items) but tell people how many results are not shown
• don't fallback to a separate search page when we have a lot of results; rely on the user instead filtering their query a bit more

Separately from the UX, it would be good to move the filtering and ranking code out of the web/ folder in order to get that under test.

Here's an image of what this would look like:

[srawlins]

increase the amount of context info we show per search item (each item becomes 2 lines tall)

Design is always tricky. We used to have something like this, then got feedback, https://github.com/dart-lang/dartdoc/issues/3171, that each item should be exactly 1 line tall, with good reasons. 🤷 CC @InMatrix

show results in a popup, scrolling list; show a max number of elements (it's not useful to see 1000 items) but tell people how many results are not shown

Yesssss I love it.

don't fallback to a separate search page when we have a lot of results; rely on the user instead filtering their query a bit more

What does this mean? What is the current fallback? Isn't it just a link at the bottom or something?

Separately from the UX, it would be good to move the filtering and ranking code out of the web/ folder in order to get that under test.

+1. Related, there are some very big impact, cheap ordering enhancements laid out here and here. Those are very simple ideas, but it's pretty important to have testable code. In that same issue is this idea which is big impact, but more complex to write.

[devoncarew]

Design is always tricky. We used to have something like this, then got feedback, #3171, that each item should be exactly 1 line tall, with good reasons. 🤷

Ah, I wasn't aware. There's probably a trade off here; it looks like that previous design was 4-5 lines tall. This one would be consistently 2 (w/ an ellipses overflow for longer descriptions). Both designs show ~the same number of items - the redux gives the popup more vertical space.

What is the current fallback? Isn't it just a link at the bottom or something?

It shows all the results in a separate, full-page UI. Users loose a bit of context w/ the transition, and I think we'd be better off just having them filter their query a bit more.

[jcollins-g]

One way of eliminating the 1000 items problem could be to downgrade a search result if it has inherited documentation. That's easy to detect, could be added as a field in the json, and the search box could just filter it out (if there are too many potential results) or use them as a last result. The examples shared in the presentation earlier this week could have been greatly reduced with this, and that's low hanging fruit.

[jcollins-g]

@srawlins We might ask @Hixie for an opinion, but reading between the lines on the feedback for #3171 I think it might be OK to have more than one line as long as all the information is useful and does not clutter the view or add too much extra whitespace. @devoncarew 's example is much cleaner than the form Ian objected to.

[srawlins]

@InMatrix might also have something to say regarding @Hixie's point about easy scanning. I totally understand how two lines per item can make it very hard to scan the autocomplete words. @devoncarew screenshot doesn't seem too bad in that respect. Maybe there are best practices about strongly emphasizing the autocomplete words, or muting the surrounding text, or about single-line entries, ... I defer to the experts :)

[InMatrix]

Thanks for sharing your proposal, @devoncarew. I think it's pretty challenging to solve all the shortcomings identified in the study by tweaking the current static search functionality in DartDoc. The study report shows three main issues: 1) similar results are not grouped (e.g., toString), 2) results ranking doesn't surface the most useful pages, and 3) there's no search history to allow quick access to previously used pages. The last two call for a backend.

Given that a lot of users appear to search Google already for Flutter API docs, maybe we can explore how far we can get with Google Custom Search? It appears to support autocompletions and structured data. Aside of not having to build and maintain our own search backend, a potential bonus is that we might be able to leverage the generative search feature as it rolls out to the public.

[Hixie]

Re the question above, I think the suggested UI but with the second line just appended to the first would be much more usable. To be honest though I would just not bother with the description.

I think there's two use cases for search here.

One is when you know (roughly) what you're looking for. You may not know exactly what class its own, but you know the member's name. All you really care about in that context is the library + class + member name, the description isn't going to be any use because the first few words are never enough to really disambiguate things with the same name (e.g. all the "sort"s in the screenshot above have the exact same description, and the "socket"-related ones don't give any information that would really help me decide which I wanted, unlike the library and class name). We currently do an OK job at this though fixing https://github.com/dart-lang/dartdoc/issues/3411 would make it much better (you never need to see inherited members in the results, by definition they're the same), and I'm sure there are other incremental improvements we could make.

The second use case is when you don't know what you're looking for and have a problem. For that you need Google-like search, and for that a longer multiline snippet is very useful because you're not just scanning class names or whatever, you're actually reading the results to find the best option. We don't really handle this use case at all currently. That's not an autocomplete drop-down type of scenario. It's a search scenario. I think it would make sense to replace the results you get when you hit enter on the autocomplete results with just the results of a google search of the domain. (The current search results page is basically just the autocomplete list with more results, which I'm not sure I've ever really wanted; I'd be curious to see metrics for how many times people use that a second time.)