Quick navigation in DocC Render

Thank you for your awesome work and engagement in this project!

I agree. I think it would be interesting to surface that functionality in a more explicit way somewhere, along the lines of what you suggested with the Nuxt website, for example, but being consistent with Xcode is a good way to start.

Excited to see the next steps of this!

2 Likes

I like the idea of using Xcode as a reference. However, since Swift is increasing its efforts towards other platforms, It could also be valuable to take a look at more "neutral" shortcuts, if they exist at all? Maybe it would be a good exercise creating some sort of table of popular softwares and their shortcuts and see if there's some sort of consensus? Might be overkill, though? Hard to think this would be a showstopper for some.

Hi @sofiaromorales
I loved your research regarding fuzzy search and algorithms. Amazing work :clap:
Thanks for sharing the article about Reverse Engineering Sublime Text’s Fuzzy Match too!

2 Likes

Congrats for being accepted :partying_face:, was sure you would nail it!

2 Likes

Hi folks! I'm very excited to announce that I will keep developing this project during the next couple of months as part of GSoC22 (:partying_face:) guided by the most amazing mentors @marinaaisa @beatriz and @franklin. With their support and the community feedback, I'll design and implement "Quick navigation in DocC Render" a new feature for the Swift-DocC-Render project that aims to help developers to navigate and discover documentation symbols easily (similar to what you achieve with “Open Quickly” in Xcode but for the web). Since this is a project for the community it would help me a lot to have your feedback during the process :)

Primarily how this will work is that the user will trigger the Quick Navigation modal either via a keyboard shortcut or a UI element, with the modal activated the user will be able to type a keyword and get a list with the symbols that have a matching name with the user input back. Something similar is already implemented on the navigator sidebar but Quick Navigation will let you make a deeper search using exact and fuzzy string matching.

I already have some designs on what this tool will look like, I was careful to follow the same style as the rest of the web to get a consistent UI but there is still a lot of point of variation where we can get creative and design something that feels native and user friendly.

The quick navigation modal itself can be in three different states, an empty state when it doesn't have any input, the results-found state when there's some input and we get some results back, and the no-matches state, when there are no matches for the user input.

The x-mark icon next to the input bar would be used to clear out the user input, and to dismiss the tool it would be either by clicking outside of the modal or selecting a symbol from the results list.

Even though there are a lot of similar tools already implemented on IDEs and web-based documentation I still have some questions regarding the UI/UX that I want to share with you

  • Which would be the best shortcut to trigger the modal in terms of discoverability and ease to remember? I've been going back and forth between ⌘ + shift + o, used in Xcode to trigger Open Quickly, and /, used in websites such as Nuxt, Tailwind, and Apollo GraphQL to activate the search bar. / is an easier one but we might want to keep persistent with Xcode

  • How many results we should show back to the user? the results are going to be ordered in a way that you will see the most relevant at the top, but from the entire list, how many listed results are a good amount? should this be a fixed number or maybe we should use some kind of percentage based on a similarity metric?

  • Been thinking that for performance reasons (considering very large documentation) we might want to trigger the search only when the user types a keyword of 3 or more characters (this is an idea that I got from Open Quickly in Xcode) if this is the case, which is the best way to let the user know this 3-characters rule?

I'm looking forward to having your feedback, either on the design or on the questions I made, and know what y'all think about this, thanks! :smile:

10 Likes

Sofía, so excited about your progress! This is looking great. I have some thoughts on your questions:

I think it would be interesting to stay consistent with Xcode since folks will often be using documentation in both places.

I'd start by using Xcode as a reference for consistency as well. It seems like the way that works is showing 8 at a time, and letting folks scroll down to see up to 20 results.

That sounds wise to me. That's pretty standard behavior for this type of component, I think folks will catch on quickly as they're using it and typing things out.

We're already halfway through GSoC (:smiling_face_with_tear:) so I decided to write about my experience working on this feature, I've made solid progress implementing the foundation of Quick navigation, and I'm looking forward to sharing a demo with you very soon, here you can read more in detail what I've been up to the last couple of weeks My GSoC’22 journey so far | Swift Org, and if you like to check the pr with my (currently WIP) code you can take a look into the swift-docc-render GitHub repo.

Already included in the post but @franklin @marinaaisa and @beatriz have been the best (and most patient) mentors :sparkling_heart:

9 Likes

Hi. Just wanted to thank @sofiaromorales for the effort. :heart:
I really appreciate that you've done great work. I think I was first to point out the search/quick navigation feature in the DocC Missing search field in hosted doc… | Apple Developer Forums and your work will fulfil this missing feature.
I am looking forward for your PR to be finished and released in latest Xcode.

2 Likes

Thanks for the message @gadireddi226. I'm glad that you find this feature valuable.


After deep rounds of review from the docc-render maintainer's team, Quick navigation finally made it into the main branch. Thanks a lot for all your support on this! :heart:

6 Likes