Minor UX and UI improvements #200
Description
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.