Hi everyone! I'm very excited to be finally participating in this forum, this is my first interaction with the community through this platform so I'm kinda nervous but I'm also happy to show up
I'm interested in working on the GSoC project "Quick navigation in DocC Render" mentored by @beatriz and @ Marina Aisa (not sure which is her handle).
DocC is a tool for building interactive and intuitive-looking documentation for your Swift frameworks, libraries, and packages. Is integrated into Xcode and creates a standardized UI with all the exposed symbols linked in a way that is very easy to navigate and understand what a certain package does and how is supposed to be used. At a high level, what this tool does is that it goes through the project files searching for documentation comments, scans the comments, formats them depending on the context, then attaches them into the build documentation. Besides of this it also supports articles and tutorials.
All this documentation can be exported into a
.doccarchive package, containing all the needed files to display the documentation comments, tutorials, and articles, either on Xcode, or shared and distributed online, having it hosted on a server. The web app generated to share the documentation on the web is a Vue application. More info about the distribution process can be found here.
Until recently the renderer of the
.docarchive on the web didn't provide an easy way to navigate through the project symbols like we do when we open the documentation in Xcode with the sidebar. This changed last month when the DocC team introduced a sidebar into the Swift-DocC-Render project (Swift-DocC-Render is the SPA powered by Vue.js used to create the code documentation website). The ideation process of the sidebar and more details about it can be read in the Swift forum Swift-DocC sidebar discussion, and the implementation details can be found on the Swift-DocC-Render GitHub repo.
Now, this sidebar doesn't have quick navigation or keyboard shortcuts to jump between symbols, so the idea here is to design and implement a natural way to accomplish this. Having quick navigation would help to move between documentation files faster in an intuitive way, increasing productivity and making the website more accessible to the user.
If I'm on the DocC render Documentation Web I might want to do the following using keyboard shortcuts:
- Move one file up on the file tree
- Move one file down on the file tree
- Go back and forth between symbols I last visited
- Focus the
Filter in **DocC-name**search bar to look for a symbol
- Filter a specific symbol type in the navigation sidebar
- Open a quick file navigation bar with more symbol filter capabilities than the current
Filter in **DocC-name**search bar has, similar to what most IDEs have (not sure if this is out of scope from the GSoC project statement)
One of the biggest challenges I see is from the UX perspective. The design process must address which key combination results in the most intuitive shortcut for the user, creating a mnemonic combination that helps the user to learn it over time, and making the shortcut unique in a way that doesn't conflict with any of the browser or O.S native shortcuts.
Questions for the community
- Any other use case you can think of?
- There's an accessibility/web standard for designing these shortcuts?
- Which are your favorite/most used keyboard shortcuts when you are navigating through your code in an IDE or web app?
- Anything that I might be missing out from the problem prompt?
- For the mentors @beatriz @ marina, there's any additional insight, documentation, or previous discussion we should take into account for making this implementation?
- Any other general thoughts about this?
Any opinions and feedback are highly appreciated!
Rn, I'm setting up the project locally on my machine to have a better sense of how it's structured and how the sidebar was integrated, I'll be sharing any update once I get my investigation going.
I hope this is the perspective of the project that the GSoC mentors had in mind, if not pls pls point me in the right direction, I'm making my best to go out of my introvert bubble here
Thank y'all for bearing with me up to this point!!