Suggestions for UX improvements

[stefanchrobot]

Hey, I'm opening this issue to suggest some user experience improvements for ExDoc. Not an UX expert, so some of these things are definitely up for discussion.

1. Delay on quick search

Typing "/string" to quick search for "string" doesn't work - some initial characters are eaten up. This might be due to the animation or throttling. Either way, this is pretty annoying.

2. "Quick-search" into a section

Some docs make great use of sections. It would be nice if they were discoverable through quick search. Here's an example: "How do I handle errors in Oban?". I'd love the quick search to suggest me the relevant section if I typed "error".

3. Expand clicked module by default

Maybe it's not the right way to do it, but when I want to have an overview of public functions on a module, I usually click the module name and then click "Functions":

That one extra click could be removed if the "Types" and "Functions" sections were expanded by default.

4. Bigger click surface and hover state for sidebar links

I think it would be an improvement for people who use mouse navigation to have a bigger clickable surface with a hover state for sidebar navigation links. Current approach:

Some idea of implementing this:

5. Link flickering on page render

For some reason, when a page is rendered, some of the links flicker (e.g. IO.Stream in this example). This might have something to do with how the styles are structured. Not sure if there's a solution to this.

[josevalim]

Thank you. I have read through and I agree PRs to fix all suggestions are welcome.

And yes, not sure if there is a fix for 5. :)

[stefanchrobot]

Great! I'll come back with a PR.

[zachallaun]

@stefanchrobot I really like these suggestions! Have you made any progress on a PR? I might take a crack at implementing some of them, but don’t want to step on your toes!

[stefanchrobot]

Hey, @zachallaun! No progress on my side on this yet, feel free to pick this up. Let me know if you'd like to take only part of this.

[zachallaun]

@stefanchrobot Thanks for getting back to me! I’ll see what I can get through and will reference this issue in the PR so you’ll know what got done and what didn’t. =)

[zachallaun]

@josevalim or anyone else — any thoughts on the correct way to handle the third suggestion? I’m just looking through the code base and having trouble finding a clean place to indicate that certain groups should be open by default. The function group is defined here, for instance, and Types elsewhere. And sometimes you might want Callbacks opened by default too, depending on the module.

I’m thinking that perhaps all groups should just open by default?

[josevalim]

After more thought, I don't think we should do 3. It works great when you want to click on functions BUT if you are just browsing modules and their definitions, now you will have to scroll through all types and functions, if you want to continue scrolling through the sidebar. I would skip it for now.