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.
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 folks! I'm very excited to announce that I will keep developing this project during the next couple of months as part of GSoC22 () 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!
We're already halfway through GSoC () 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.