docs: Improve clarity and usability of VS Code Code Navigation tutorial #156
Conversation
…de Navigation tutorial
arshinsikka
force-pushed
the
improve-code-navigation-tutorial
branch
from
47bec05 to
22b9b32
Compare
|
@Johnwz123 (and others), for your inputs ... |
Johnwz123
left a comment
Johnwz123
left a comment
There was a problem hiding this comment.
Thanks for the updates! Just one comment regarding the Mac commands added for consistency of formatting. Otherwise, LGTM.
tutorials/vscCodeNavigation.md
Outdated
| You can search for symbols in the current file or workspace to navigate your code more quickly. | ||
|
|
||
| To search for a symbol **in the current workspace**, press `Ctrl+T` and enter the name of the symbol, then select from the list of matches to navigate to its location. | ||
| To search for a symbol **in the current workspace**, press `Ctrl+T` (`Cmd+T` on Mac) and enter the name of the symbol, then select from the list of matches to navigate to its location. |
There was a problem hiding this comment.
For the addition of the Mac commands, would be good if you can update to follow the format: "({{ icon_windows }}/{{ icon_linux}} Ctrl+Shift+E | {{ icon_apple }} Cmd+Shift+E)" (See "Explorer view..." under the "Code Navigation" section at the top of the page) to keep it consistent across pages.
Same goes for the other Mac commands added in the page.
There was a problem hiding this comment.
Hi @Johnwz123, thanks for pointing that out 🙏
I’ve updated the shortcut formatting across the page to use the consistent icon macro style (e.g., ({{ icon_windows }}/{{ icon_linux}} … | {{ icon_apple }} …)), and cleaned up the Quick Open and Peek Definition lines accordingly. This should now match the style used in the rest of the Code Navigation docs.
Let me know if you spot anything else that could be improved!
…ss review feedback
damithc
left a comment
damithc
left a comment
There was a problem hiding this comment.
Some cosmetic changes suggested.
| <box type="tip" seamless> | ||
| If the Java Projects or Outline view does not appear, ensure that: |
There was a problem hiding this comment.
| <box type="tip" seamless> | |
| If the Java Projects or Outline view does not appear, ensure that: | |
| <box type="tip" seamless> | |
| If the Java Projects or Outline view does not appear, ensure that: |
There should be blank line between a tag and text. Fix in other places too.
| If the Java Projects or Outline view does not appear, ensure that: | ||
| - A Java file is currently open | ||
| - The Java Extension Pack is installed from the Extensions Marketplace | ||
| - Your project follows a recognized structure (e.g., `src/main/java`) |
There was a problem hiding this comment.
As per our Markdown coding standard, use * for bullets.
|  | ||
|
|
||
| ## Search for Symbols | ||
| Symbol search helps you quickly locate and jump to methods, classes, and variables across your codebase. |
There was a problem hiding this comment.
Leave a blank line between a heading and the next paragraph, for better readability.
| You can quickly view or navigate to the definition of a class, method, or variable in your code to understand and trace how different parts of your project are connected. | ||
|
|
||
| To view a symbol's definition without leaving your current location, place your cursor on the symbol and press `Alt+F12`. Alternatively, right-click on the symbol and select **Peek > Peek Definition** from the context menu. | ||
| To view a symbol's definition without leaving your current location, place your cursor on the symbol and press ({{ icon_windows }}/{{ icon_linux}} Alt+F12 | {{ icon_apple }} Option+F12). Alternatively, right-click on the symbol and select **Peek > Peek Definition** from the context menu. |
There was a problem hiding this comment.
For keys, use either Alt or Alt (i.e., <kbd>Alt</kbd>)
4 participants
This PR enhances the "VS Code - Code Navigation" tutorial by improving clarity, accessibility, and user experience for students. It addresses Issue #155 and implements the following changes:
✅ Summary of Improvements
1. Add brief introductions for key features
2. Include Mac shortcut equivalents
Cmd+T,Cmd+P) alongside allCtrl+shortcuts across the guide.3. Add troubleshooting tip box for missing views
<box type="tip">block below the Projects View section with guidance for resolving missing Java Projects or Outline views.4. Add Quick Open filter summary
@,#,:) at the end of the "Search for Symbols" section.5. Add shortcut summary table
Please let me know if further refinements are needed.