[Pitch] Quick navigation in DocC Render

I hink simple typo tolerance when just switching two chars (by far my most common typo) would be nice - it could be done as a fallback if there are zero hits for a search only (as there typically would be in that case) so no overhead when not doing typos.

2 Likes

Generally true, but in the context of a text input form element it typically only selects the focused text content. EG. you can try Command+A in this forum's search bar, or the sidebar search bar in the docs, and it only selects the text in the search bar.

3 Likes
  1. This has been a topic of discussion during the development of the feature. The current placement is temporal because, as you mentioned is not very visible, and the user might get confused expecting that, since it's inside the sidebar input filter, it will trigger an action related to that component, on the other hand, since both have similar functionalities we wanted to keep the button near to the sidebar, but then it wouldn't be visible when is hidden, do you have any preference of where the open-modal button should be placed?

  2. I wonder if there's any other browser where the keyboard shortcuts are colliding, I prefer not overriding the native implementations, so I'm glad we have both to open the modal :)

Thanks for the feedback @ole!

1 Like

Really great work here @sofiaromorales! UX-wise, this is quite delightful to use. Some questions/comments:

  1. I share @bzamayo's feedback regarding the performance of it. ArgumentParser is not a huge library, so I'm wondering what the cause of the slight delay is. Reducing that delay will make the experience feel even quicker.

  2. I feel like the / button is misplaced. I'm all for making this feature more discoverable, but when it's placed inside the navigator filter bar, it feels like pressing / will focus the navigator filter bar rather than present a modal. I'm wondering if a :mag: icon next to the new toggle sidebar button could work. That way the feature is discoverable whether the sidebar is enabled or not.

  3. I'm not sure that ESC label in the Quick Navigation bar is useful. On narrow viewports, I'd expect to take up space away from the query string. I feel like it's a common expectation that the Escape key closes modals, so I'd lean towards not including the label at all and keep the design simpler.

I also filed some small bugs to make sure we don't lose track of them :) Issues · apple/swift-docc-render · GitHub

Amazing work!

1 Like

@sofiaromorales On some further investigation, I believe the feeling of 'slowness' is mostly being caused by the key input events being debounced by 500ms on every key press here. AFAICT, this is unnecessary and simply removing that delay (or reducing it to something lower like 10-50ms) would help a lot.

1 Like

Hello Sofia, this looks great I just have a few small things:

  1. Would users be able to use this on mobile devices or its only meant for desktop?
  2. Same as other users have pointed out, I think we should move the icon to toggle it somewhere else. You may close the navigator, so it becomes hidden. Also this way it feels like part of the Navigator, which it is not.
  3. Sorry I missed this in the initial discussions, but I’m wondering what was your thought process regarding uses of navigator sidebar filtering vs. Quick Navigation? Are there specific scenarios you expect to use one over the other, and how does that impact how you’ve decided to display results?
1 Like

Great work! Thanks :pray:

1 Like

Typo tolerance would have to be implemented using some distance calculation algorithm like the Levenshtein distance. I did consider this at first, but then I realized that most of the similar features in text editors and IDEs don't include this type of tolerance either. I can't tell for sure if this would impact the app's performance, but it wasn't scoped as part of the project (in terms of what GSoC refers to). We could consider it as part of a future direction tho, I did some research regarding this when I was scoping the proposal for the feature Quick navigation in DocC Render - #12 by sofiaromorales.

I see, that's an interesting observation, I'll be including that behavior in the feature, thanks!

1 Like

This is so cool; really compelling and fun to use!

Small additional thought: I really like having the / icon exposed to help teach people that they can open the UI without using a mouse.

1 Like

[Reposting because the images didn't go through the first time]

Hey Sofía, fantastic work! This feels intuitive and super useful.

Some minor improvement suggestions:

  1. I agree with the concerns listed above on the placement of the "/" button.

  2. It would be awesome if the window height was sized to cut off around half the last result of the list, if there are more results than fit in the view at a single time. This would indicate that there are more results available. A good example of this is Xcode Open Quickly:

  1. There's a lot of padding right now, I'd suggest condensing it a bit to make better use of the available space on the window. I took a quick pass at this to show what I mean:

  1. Another small polish detail, would be nice if the placeholder text color matched the filter's placeholder text color. Looks like right now it's a lighter gray.

Again, fabulous work!

Like @bzamayo mentioned the delay is caused by a debounce on the filter input, initially, I set it to 500ms keeping the same delay as in the sidebar input, but reducing it to 250ms would make the experience faster

I agree that the open modal button should be on the nav bar, but placed on the right hand, I find that most websites keep the upper right for the filter, besides this, adding not only the magnifier icon but keeping the / icon so people knows how to open it with the keyboard.

I do like providing the alternative for people to close the modal using the ESC button, I have seen it on multiple websites, and it has the advantage that is adding a focusable element to perform the action, so instead of removing it I would try to make it smaller so it doesn't take that much space

Great thanks! :smile:

Really great work!

Minor nit:

The subtitle of each result seems to be lowercased (e.g "parsablecommand", "arrayparsingstrategy"). Can we keep its original case?

1 Like

Thank you for all your great comments! Over the past few weeks I've been polishing the feature and making some changes based on your feedback.

Some of these changes include:

  • New button to open the Quick navigation modal, a magnifying glass icon located to the right of the top navigation bar, making the feature more visible and accessible even with the sidebar collapsed
  • Hierarchy of symbols keeping the original case
  • Reduced debounce time for faster query results
  • Minor UI refinements
  • Performance improvements

You can take a look at this updated demo.

This feature was for desktop only, but I'd like to know your thoughts on making this accessible on mobile as well.


Quick navigation is still under code review, but I'll make an update once it has gotten merged into the main codebase.

For now it will only be available under the quickNavigation feature flag, but I hope to see it as part of docc-render by default later on.

Although GSoC is ending next week and the original scope of the project is complete, I plan to continue improving Quick Navigation by working on some additional features, one of these being symbol previews in the modal, similar to Spotlight. If you have other ideas that you would like to see as part of this feature in the near future, feel free to share them :)

Once again, thanks for the feedback!

10 Likes

Thanks for your feedback! Quick Navigation has landed in the main branch :tada:

Currently is under a feature flag, please try it out and let me know what you think of it - this is how you can enable it in your documentation Documentation

3 Likes

I'm happy to announce that Quick Navigation now comes as a default feature in DocC-Render and is available in both 5.8 dev and the nightly toolchain :partying_face::tada:

After requesting the enablement, Quick Navigation made it into the main and 5.8 release branches last week, and, as requested by the project maintainers, could still be disabled by the developer through the theme-settings.json file.

Once again, thank you all for helping me build this!

13 Likes

Great :+1:

Hope replacement (or an option to hide) for the current sidebar approach. Just remove space and is confuse. The content should be on the center.

1 Like

It seems that we can already hide the sidebar :clap:
My iPad Pro 11 thanks you :wink:

Hey everyone. I just opened a Swift-DocC-Render pull request to make an optional enhancement to this awesome feature that @sofiaromorales originally pitched here and implemented.

With a feature flag enabled, DocC users can opt-in to a quick navigation UI where the selected filter result is previewed on the right hand side of the results pane, like in this example screenshot:

This would allow DocC users to more quickly preview the results before they navigate to the actual pages.

If there is generally positive feedback about this enhancement, I think it would make sense to phase out the feature flag requirement and make this the default experience.

Thanks again @sofiaromorales!

5 Likes

@marcus_ortiz This looks great! I think it's a great addition to Quick Navigation, and I'm entirely into making it the default experience. I updated the prototype with Quick Nav Preview so people can test it Quick Navigation Preview - Swift ArgumentParser.

The only detail I could point out is that for default implementations symbols, it might make sense to hide the preview or display a No overview available text. For example, searching for Expressible returns a list of default implementation symbols that do not display any info in the preview.

I still think it's great as it is, I'm a big fan of this enhancement, and I would like to see this as part of QN by default once the pr is ready. Thanks for your work on this!

1 Like

Another option could be to hide those from Quick Nav results or rank them low enough that people rarely see them. Or, perhaps, the preview could show the page's topics instead.