From cdfe04d9fcfeec7c3fd772cb6fd455d359c81bf9 Mon Sep 17 00:00:00 2001 From: BeckyK102125 <158101496+BeckyK102125@users.noreply.github.com> Date: Sat, 7 Mar 2026 19:21:43 -0500 Subject: [PATCH 1/3] Add welcome guide for open source contributions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Create docs/welcome.md — a beginner-friendly guide that explains what open source is, who can contribute, what makes a good first contribution, how to find issues, how to get help, and what happens after a PR is merged. The file includes TODOs for expanding accessibility guidance and tips on reading issues, and contains a few typos that should be proofread. Last reviewed date is included at the end of the document. --- docs/welcome.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 docs/welcome.md diff --git a/docs/welcome.md b/docs/welcome.md new file mode 100644 index 0000000..985608b --- /dev/null +++ b/docs/welcome.md @@ -0,0 +1,81 @@ +# Welcome to Open Source Contribution + +This guide is for people who are new to contributing to open source software. It explains what contribution means, who it is for, and how to get started. + +--- + +## What Is Open Source? + +Open source software is software whose source code is publicly available. Anyone can read it, use it, and - in most cases - contribute to it. Contributions can include: + +- Fixing bugs in the software +- Writing or improving documentation +- Filing bug reports +- Reviewing other people's changes +- Translating content into other languages +- Improving accessibility + +You do not need to be a professional developer to contribute. Documentation, accessibility improvements, and bug reports are among the most valuable contributions an open source project can receive. + +--- + +## Who Can Contribute? + +[TODO: Add a paragraph explaining that contributors come from all backgrounds, skill levels, and countries. Emphasize that using assistive technology is not a barrier to contribution - in fact, AT users bring a perspective that improves projects for everyone.] + +Anyone who writes code can contribute to open source. Contributors come from all walks of life and have all levels of skill. Some develop as their day job, others as a hobby and still other are just starting out on their journey of learning and developing code. +Those who use AT bring a wealth of knowledge as they know many pain points of where their AT just doesn't work. They can be just as if not more successful than developers who do not use AT. They can assist those developers who aren't aware of or do not know accessibility in learning about its importance. + +--- + +## What Makes a Good First Contribution? + +A good first contribution is: + +- **Specific** - it addresses one problem clearly +- **Scoped** - it does not try to fix everything at once +- **Described** - the PR or issue explains what changed and why +- **Tested** - for documentation, this means reading it aloud with your screen reader before submitting + +--- + +## Finding Something to Work On + +Most open source projects label issues that are suitable for new contributors. Look for: + +- `good first issue` +- `first-timers-only` +- `help wanted` +- `beginner` + +[TODO: Add two or three sentences about how to read an issue to decide if it is right for you. What questions should you ask yourself? Is the description clear enough? Is anyone else already working on it?] + +Determine do you have the skills needed and the time to commit to taking it on? Intent is great, but code and troubleshooting/testing takes time. To read an issue go to the reponame/issues then locate and open the issue and read through what the problem is, what the expected result should be etc. + +--- + +## Getting Help + +It is always acceptable to ask a question on an issue or pull request. Good questions: + +- Are specific: "I'm trying to fix the broken link on line 24 of setup-guide.md. The link currently points to /docs/old-setup. Where should it point?" +- Show what you tried: "I searched the repository for the correct URL but couldn't find it" +- Are polite: assume good intent from maintainers, even if they are slow to respond + +--- + +## After Your Contribution Is Merged + +When your pull request is merged: + +- Your name appears in the project's commit history permanently +- The issue you fixed is closed +- You are officially listed as a contributor to this project + +[TODO: Add a sentence or two about what this means for someone's GitHub profile and open source portfolio.] + +When you code is merged into a larger github repo that's somethign for your devloper resume. Its says I helped develop this. The more contributions you make, the more that resume grows and the more respect and renound you become in the open source community. + +--- + +\*Last reviewed: 03-7-26 From 107f65b46f976425868c081a31be96c1f986eda5 Mon Sep 17 00:00:00 2001 From: BeckyK102125 <158101496+BeckyK102125@users.noreply.github.com> Date: Sun, 8 Mar 2026 17:23:55 -0400 Subject: [PATCH 2/3] Add keyboard shortcut guide for screen readers Add a new docs/keyboard-shortcuts.md file providing a comprehensive reference of keyboard shortcuts for navigating GitHub with NVDA, JAWS, and VoiceOver. Includes single-key navigation, mode-switching, reading commands, screen-reader-neutral page shortcuts, common form/input keys, and troubleshooting/workarounds to improve accessibility guidance for assistive-technology users. --- docs/keyboard-shortcuts.md | 148 +++++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 docs/keyboard-shortcuts.md diff --git a/docs/keyboard-shortcuts.md b/docs/keyboard-shortcuts.md new file mode 100644 index 0000000..4cf2ec0 --- /dev/null +++ b/docs/keyboard-shortcuts.md @@ -0,0 +1,148 @@ +# Keyboard Shortcut Reference + +## GitHub Navigation with Assistive Technology + +This reference lists keyboard shortcuts for navigating GitHub with a screen reader. It covers three screen readers: NVDA, JAWS, and VoiceOver. + +--- + +### NVDA (Windows) + +NVDA is a free, open source screen reader for Windows. Download it from [nvaccess.org](htps://nvaccess.org). + +#### Single-Key Navigation (Browse Mode) + +Use these keys to jump to specific element types on any GitHub page. + +| Key | Moves to | +| ------- | -------------------------- | +| H | Next heading | +| Shift+H | Previous heading | +| 1-6 | Next heading of that level | +| K | Next link | +| B | Next button | +| F | Next form field | +| T | Next table | +| D | Next landmark region | +| L | Next list | +| I | Next list item | + +#### Switching Modes + +| Key | Action | +| ------------ | ----------------------------------------------------- | +| Insert+Space | Toggle between Browse Mode and Focus Mode | +| Insert+F7 | Elements list (links, headings, form fields, buttons) | + +#### Reading Commands + +| Key | Action | +| ------ | ----------------------------------- | +| NVDA+↓ | Start reading from cursor (Say All) | +| NVDA+↑ | Read current line | +| Ctrl | Stop reading | + +--- + +### JAWS (Windows) + +JAWS (Job Access With Speech) is a professional screen reader for Windows made by Freedom Scientific. + +### Single-Key Navigation (Virtual Cursor) + +| Key | Moves to | +| ------- | -------------------------- | +| H | Next heading | +| Shift+H | Previous heading | +| 1-6 | Next heading of that level | +| U | Next unvisited link | +| K | Next link | +| B | Next button | +| F | Next form field | +| T | Next table | +| R | Next landmark region | + +### Switching Modes + +| Key | Action | +| ------------ | ----------------------------------- | +| Enter | Activate Focus Mode on a form field | +| Insert+Z | Toggle Virtual PC Cursor | +| Num Pad Plus | Open PC Cursor (exit forms mode) | + +### Reading Commands + +| Key | Action | +| -------- | ----------------------------------- | +| Insert+↓ | Start reading from cursor (Say All) | +| Insert+↑ | Read current line | +| Ctrl | Stop reading | + +--- + +### VoiceOver (macOS) + +VoiceOver is the built-in screen reader on macOS. Activate it with Command+F5. + +The VoiceOver modifier key (VO key) is Control+Option. + +#### Rotor Navigation + +The Rotor is VoiceOver's navigation hub. Open it with VO+U, then use ←/→ to switch between element types, and ↑/↓ to navigate within a type. + +Element types available in the Rotor: Headings, Links, Form Controls, Tables, Landmarks, Web Spots. + +#### VO Commands for GitHub + +| Command | Action | +| ------------- | ----------------------------- | +| VO+U | Open Rotor | +| VO+Right/Left | Move forward/backward | +| VO+Up/Down | Adjust setting in Rotor | +| VO+Space | Activate current element | +| VO+Shift+Down | Interact with current element | +| VO+Shift+Up | Stop interacting | +| VO+A | Start reading from cursor | +| Ctrl | Stop reading | + +--- + +## Screen-Reader-Neutral Shortcuts (All Screen Readers) + +These shortcuts work in GitHub regardless of screen reader, because they are browser or operating system shortcuts. + +## GitHub Page Shortcuts + +| Key | Action | +| -------- | ------------------------------------------------ | +| ? | Show keyboard shortcut help for the current page | +| G then I | Go to Issues tab | +| G then P | Go to Pull Requests tab | +| G then C | Go to Code tab | + +### Form and Input + +| Key | Action | +| ---------- | ----------------------------------------------- | +| Ctrl+Enter | Submit a comment or form | +| Tab | Move to next focusable element | +| Shift+Tab | Move to previous focusable element | +| Enter | Activate a focused button or link | +| Space | Check/uncheck a checkbox; activate a button | +| Arrow keys | Navigate within a radio group, tab bar, or menu | + +--- + +## Common Issues and Workarounds + +**NVDA reads the GitHub page too slowly:** +In NVDA Settings → Browse Mode → increase Maximum number of characters on one line to 10000. + +**JAWS loses track of where I am on the Issues list:** +Press JAWS key + F5 to re-read the current page. If that does not help, refresh the page (F5) and navigate fresh. + +**VoiceOver does not read new content when filter results refresh:** +GitHub issue list filtering updates via JavaScript. If VoiceOver does not announce the updated count, navigate to the heading of the list (H key) and read from there. + +**The diff table in Files Changed is hard to read:** +The improved Files Changed experience has been broadly rolled out and is likely already active for your account. If you are experiencing issues with diff navigation or missing landmarks, verify using your screen reader: activate the **User Menu** button → **"Feature preview"** → look for **"New Files Changed Experience"**. If it appears, the toggle announces **"Pressed"** when enabled - activate it if not. If it no longer appears in the Feature Preview list, it has graduated to the standard interface and is active automatically. From 3c14fbeb622fd9e58856cbd4b8d971a5a1441736 Mon Sep 17 00:00:00 2001 From: BeckyK102125 <158101496+BeckyK102125@users.noreply.github.com> Date: Sun, 8 Mar 2026 17:28:17 -0400 Subject: [PATCH 3/3] Adjust heading levels in keyboard shortcuts doc Update markdown heading hierarchy in docs/keyboard-shortcuts.md: demote JAWS subsections from H3 to H4 and promote "Screen-Reader-Neutral Shortcuts" from H2 to H3 for improved structure and consistency. --- docs/keyboard-shortcuts.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/keyboard-shortcuts.md b/docs/keyboard-shortcuts.md index 4cf2ec0..c310ec8 100644 --- a/docs/keyboard-shortcuts.md +++ b/docs/keyboard-shortcuts.md @@ -48,7 +48,7 @@ Use these keys to jump to specific element types on any GitHub page. JAWS (Job Access With Speech) is a professional screen reader for Windows made by Freedom Scientific. -### Single-Key Navigation (Virtual Cursor) +#### Single-Key Navigation (Virtual Cursor) | Key | Moves to | | ------- | -------------------------- | @@ -62,7 +62,7 @@ JAWS (Job Access With Speech) is a professional screen reader for Windows made b | T | Next table | | R | Next landmark region | -### Switching Modes +#### Switching Modes | Key | Action | | ------------ | ----------------------------------- | @@ -70,7 +70,7 @@ JAWS (Job Access With Speech) is a professional screen reader for Windows made b | Insert+Z | Toggle Virtual PC Cursor | | Num Pad Plus | Open PC Cursor (exit forms mode) | -### Reading Commands +#### Reading Commands | Key | Action | | -------- | ----------------------------------- | @@ -107,7 +107,7 @@ Element types available in the Rotor: Headings, Links, Form Controls, Tables, La --- -## Screen-Reader-Neutral Shortcuts (All Screen Readers) +### Screen-Reader-Neutral Shortcuts (All Screen Readers) These shortcuts work in GitHub regardless of screen reader, because they are browser or operating system shortcuts.