Minor UX and UI improvements

[Katrix]

Thought I'd leave a list of smaller UI and UX issues that I feel would make scala3doc more intuitive. These aren't big changes (for the most part) just more nitpicks. Sorry if this feels a bit rambly. It probably is.

First off, the packages:

Now, from what I've understood, having actual sites for packages is an intentional design choice. There's still the arrow on the side that you can click if you just want to expand the tree. However, currently there's little indication that this won't just do the same as clicking on the package name. There's not an underline when you hover over it, but that's easily missable. The arrow button itself is also quite small, smaller than I'd expect at least. (I just barely missed it several times when I tried to click it while writing this.)

Something like this (rough example) would be at least an improvement. Maybe make the arrow button also change color independently when hovered over, to further give the expectation that it is it's own separate thing.

Search bars:

There are currently 2 search bars on the page. Why?

Of the two search bars, the one on the left feels much more intuitive to use. It's more visible, has a larger area I can click on to start typing, and doesn't try to be super smart about how it interprets what I type.

The central search bar on the other hand feels like it's hidden away in the corner. Once I click on it, it's large and gives me lot's of information about where something was found, and it's signature, and that feels great. Why can't it just always have such a large click area though? It also feels like this search bar gives me stuff I care about at the top, and then as it goes on further down, I really question why those results show up at all.

Sidebar header

This image doesn't take you anywhere. I'd expect it would. On both Scaladoc and Dottydoc it takes you to what would be considered index.html

Browsing vs reading

Something I feel Scaladoc does very well is that it understands when you're browsing types and members, and when you're reading the details. As an example, let's take the type tests from the standard library.

First off, everything aligns around the name of the thing, which keeps the focus on the name. Next, each member doesn't take up that much space. It's there, that's what you need to know. It also gives you a short summary of what it is. For Scaladoc, just a single sentence.

If you want to know more, you can then either click on the member to navigate to it's page, or just click on the box it's in to get a bit more info.

This is something that both Scaladoc and Dottydoc has, but scala3doc seems to take a slightly more middle of the road approach. While both approaches are in some way valid, I much prefer the Scaladoc approach here.

In the above picture, there was 4 members from Scaladoc. Here's what 4 members in scala3doc looks like. While the headers give it a bit more orderly feeling, I feel they aren't pulling their weight enough in the amount of information they provide that isn't immediately then conveyed by the signature on the next line. Maybe if the header was the signature it'd be different, but not quite sure how well that would work.

Package vs object

Lastly, this is more a question on if something can be done better.
A few weeks ago, I was doing some compile time programming with Dotty, and I wanted to look a bit at mirror in the docs. So I went looking for the scala.deriving package, but I couldn't find it. Turns out, it wasn't a package, but an object. Maybe scala3doc could make this distinction less important? When I'm looking for scala.deriving.Mirror, I'll probably look for something named scala.deriving. Maybe scala3doc could also show the dropdown for objects containing other classes and traits, something clearly common in typical Scala.

Again, sorry if this felt a bit nitpicky and rambling. Looked like scala3doc had progressed enough that it might be time for feedback like this soonish.

[pikinier20]

Thank you for sharing your thoughts. We very much appreciate feedback coming from community. I will try to comment your thoughts.

1. Arrows on package menu
   Thank you for reporting problem with arrow. Ofc it will be fixed.

2. Search bars
   Search bar on the left is old search bar that came with dokka and tbh I forgot about its existence, it's not very smart and it doesn't contain any information except symbol name which is very confusing in e.g. overloaded methods. It's very likely to be removed. About the right searchbar: further results may be strange because this searchbar does a fuzzy search.

3. Sidebar header
   Good point

4. Lists of members
   Appearance of members is very likely to be changed to look more like "scaladoc".

5. Package vs object
   This one we need to discuss as it may be nice feature, but it also may be misleading in some cases

[TheElectronWill]

Looked like scala3doc had progressed enough that it might be time for feedback like this soonish.

Definitely! It's good to see that some people are starting to use scala3doc and to give some feedback.

Some comments in addition to Filip's:

• The arrow could indeed be more visible, especially on hover. Maybe there could also be a tooltip "expand package" on the arrow.
• The style of the main (top-right, fuzzy) search bar is a bit problematic to override for now, it will be easier in the next Dokka release. I can think of several solutions to make it more visible. I'll try them.
• For reference, we've started to discuss the layout of the members in Show declaration before documentation #139

[Katrix]

What are the current plans for the fuzzy search? Currently it feels like it just looks for all the characters in the search string in order in the entries. Something like this

entry.toLowerCase.foldLeft(search.toLowerCase)((acc, c) => if (acc.startsWith(c.toString)) acc.substring(1) else acc).isEmpty

Think it's more to it than that, but currently the above doesn't feel that helpful. Four reasons for me.

It's current problems

1. It seems like it's matching the whole signature. When I'm searching for stuff, I'm normally just interested in the name of what I'm searching for.

2. If it's a string that's commonly part of a larger string, then there's not that big of a chance that I get back what I'm looking for. For example, if I want to find the Tuple object, I might search for tuple. I won't get back the Tuple object until way down, even though it is one of the names with the least amount of difference between the entry name and the search string.

3. There might be LARGE distances between where it found each character in the search string, and it doesn't feel like there's much reason behind how these are ordered.

4. Fear of missing something. If I search for mirror, I get a long list of results. Only two of those are even somewhat related to what I'm looking for (the mirror types, which btw don't show up in the search at all). I'd rather all the bad results just didn't show up at all, so that I wouldn't have to look through what feels like garbage results.

Also, shouldn't packages also show up in the search? Confused me for quite some time.

What I'd like to see

There are three things I'd like to see from the fuzzy search.

1. A way to to turn it of. Sometimes It's just not helpful, and I'd more just like a string submatch search.

2. Handle spaces as separate searches. If I search for mirror deriving currently, it does nothing. What would be great is if that search would return all results that match both mirror and deriving.

3. Better case handling. What I'd love to see is if the fuzzy search handled case better. Seems to be something happening here currently, but not quite sure what. Part of this would just be default, and part of it would be with a special case sensitive mode. What I'd love to see for example is if I searched for NET as an acronym, it would return all the entries where the camel case matched this. In this example, NonEmptyTuple for example.

[pikinier20]

1. It seems like it's matching the whole signature. When I'm searching for stuff, I'm normally just interested in the name of what I'm searching for.

It's a bug, it shouldn't. It's strange because it works good in dokka.

[pikinier20]

OK, now it seems that problems mentioned in this issue are currently solved. The only thing in progress is new searchbar which will involve improvements described here, see #11021. Given that and the fact that we migrate our issues to dotty repo now, I think I will close this issue.