Thank you for helping improve this workshop. Whether you are a participant who found a typo, someone who wants to add a new exercise, or an educator adapting these materials for your own community - your contribution is meaningful and welcome.
This guide covers contributing to this workshop learning repository. For contributing to Accessibility Agents itself (the project you work on during Day 2), see Accessibility Agents' CONTRIBUTING.md.
- Who This Is For
- What Kinds of Contributions Are Welcome
- Before You Start - Fork and Clone
- Contribution Workflow - Step by Step
- Writing and Style Guidelines
- Accessibility Requirements
- HTML Documentation Build System
- Screen Reader Guidance for Commands in This Document
- Submitting Your Pull Request
- What Happens After You Submit
- Questions and Discussion
Workshop participants: You have already completed the contribution workflow during the workshop. This repository is an excellent first contribution target for applying what you practiced.
Educators and facilitators: You are welcome to fork the entire repository and adapt the materials for your own workshop program. Attribution is required under the CC BY 4.0 license - please include a credit line and link to the original repository.
Accessibility practitioners: If you have domain expertise in a particular screen reader or assistive technology and notice something that is incorrect or incomplete, please open an issue or submit a correction. Your expertise is exactly what this documentation needs.
People who find bugs: A broken link, a command that has stopped working, an exercise that cannot be completed - all of these are legitimate bugs. Open an issue the same way you would for any software project.
- Corrections: Wrong keyboard shortcut, screen reader command that has changed, broken external link, outdated UI description
- Clarity: A step that was confusing, an assumption that left someone behind, a paragraph that should be two
- Gaps: A common question that the documentation does not answer, an exercise step that was skipped
- New content: An additional exercise, a section about a tool or workflow not yet covered, a translation
- A command in the workshop exercises that does not work as described
- A screen reader behavior that differs from what the documentation says
- A broken link or missing image
- An exercise that assumes knowledge introduced later in the workshop
- New exercises that reinforce a concept
- Facilitator notes based on running a session
- Timing adjustments based on real session experience
- Alternative approaches for participants on different operating systems
- Rewriting the complete voice or structure of the workshop - if you have large-scale ideas, open a discussion first
- Adding content about tools or platforms not currently mentioned in the workshop
- Automated link-checking or content generation without human review
You learned this workflow during the workshop. Here it is again as a reference.
Security: We strongly recommend enabling Two-Factor Authentication (2FA) on your GitHub account. If you cannot enable 2FA, add an SSH key or create a Personal Access Token (PAT) with repo scope before contributing. If you need help, contact the workshop organizers.
- Navigate to the workshop repository on GitHub
- Activate the Fork button (top right of the repository page)
- Select your account as the fork destination
- Wait for the fork to complete - you will be redirected to your copy
Screen reader users:
- NVDA / JAWS: Navigate by button (
B) to find "Fork" - VoiceOver:
VO+Right Arrowto find "Fork" button,VO+Spaceto activate
git clone https://github.com/[your-username]/[workshop-repo-name].git
cd [workshop-repo-name]This keeps your fork synchronized with the original repository:
git remote add upstream https://github.com/[original-owner]/[workshop-repo-name].gitVerify both remotes are configured:
git remote -vExpected output:
origin https://github.com/[your-username]/[workshop-repo-name].git (fetch)
origin https://github.com/[your-username]/[workshop-repo-name].git (push)
upstream https://github.com/[original-owner]/[workshop-repo-name].git (fetch)
upstream https://github.com/[original-owner]/[workshop-repo-name].git (push)
This is the same workflow you practiced during the workshop, applied to a real contribution.
Always start from a current copy of the main branch:
git checkout main
git fetch upstream
git merge upstream/main
git push origin mainOne issue or topic per branch. Branch names should describe the change:
git checkout -b fix-nvda-shortcut-section-05
git checkout -b add-exercise-03-alternative-macos
git checkout -b update-broken-links-resourcesEdit the file or files. Limit your changes to what is described in your branch name. Unrelated improvements belong in separate branches and separate pull requests.
In VS Code:
- Open the file in the Explorer (
Ctrl+Shift+E) - Make your edits
- Save (
Ctrl+S)
In the GitHub web editor:
- Navigate to the file
- Activate the pencil icon (Edit this file)
- Make your changes
- Use "Commit changes" to save directly to your branch
Write a commit message that a future contributor can read and understand without context:
git add docs/04-working-with-issues.md
git commit -m "fix: correct NVDA virtual cursor toggle shortcut in Section 3
The documented shortcut was NVDA+Space which is correct for switching
between browse and focus mode, but the exercise called it 'reading mode'
which is not a term NVDA uses. Updated to match NVDA's own terminology."Commit message format:
type: short summary (under 72 characters)
Optional longer explanation of why the change was made, not just what
changed. What problem does this solve? What was wrong before?
Types: fix, docs, exercise, style, chore
git push origin fix-nvda-shortcut-section-05- Navigate to your fork on GitHub
- A banner should appear: "Compare & pull request" - activate it
- If no banner appears: Activate the Pull requests tab → New pull request → change the compare branch to your branch
- Fill in the PR template (see below)
- Submit
- Imperative mood for instructions: "Navigate to the Issues tab" not "You should navigate to the Issues tab"
- Present tense: "The button opens a dialog" not "The button will open a dialog"
- Specific: Name the exact shortcut, exact menu item, exact element to look for - do not say "click the appropriate option"
- Screen reader aware: Include landmark context, not just visual position ("the Save button in the dialog footer" not "the blue button on the right")
- Use heading levels consistently - H2 for major sections, H3 for subsections, H4 sparingly
- Use numbered lists for sequential steps - the order matters and participants need to count steps
- Use bulleted lists for options, items where order is unimportant
- Use code blocks (
```) for all commands, keyboard shortcuts in context, and file paths - Inline code (
``) for short references to a key name, command name, or file name
Format all keyboard shortcuts in a table when listing more than two:
| Action | NVDA | JAWS | VoiceOver |
|---|---|---|---|
| Focus search | / |
/ |
/ |
When mentioning a single shortcut inline: use backticks - NVDA+F7
- Link text should describe the destination - not "click here" or "this guide"
- Good:
[NVDA User Guide](https://www.nvaccess.org/files/nvda/documentation/userGuide.html) - Bad:
[click here](https://www.nvaccess.org/files/nvda/documentation/userGuide.html)
Every document in this repository is used by screen reader users. Accessibility is not a nice-to-have - it is the primary requirement. All contributions must meet the following:
- Every heading must be in-sequence (no skipping from H2 to H4)
- Every document must have exactly one H1 (
#) - the page title - Headings must accurately describe the content they introduce
- No bare URLs in running text - always use descriptive link text
- Exception: the Resources document may list URLs in table columns labeled "URL" for copy-paste use
- Every image requires meaningful alt text
- Alt text describes what the image shows, not just its label
- Decorative-only images (rare in documentation) may use empty alt
alt="" - This workshop avoids screenshots of UI because screen reader users cannot use them - prefer text descriptions and keyboard instructions
- Every table must have a header row using
|---|separator syntax in Markdown - Table headers must be meaningful and concise
- Avoid merged cells - Markdown tables do not support them, and they create complex reading order for screen readers
- All terminal commands use fenced code blocks with language specified (
```bash) - Inline code for short references uses single backticks
- Commands that produce output should show the expected output separately, labeled
This repository maintains HTML versions of all Markdown files. The HTML is built locally and committed alongside the Markdown source, so both formats are always in sync.
Local build, committed output:
- You edit
.mdfiles, then runnpm run build:htmlbefore committing - Both the Markdown changes and the updated
html/output are committed together - There is no CI pipeline - the build is your responsibility before pushing
What gets converted:
- All markdown files in
docs/ - All markdown files in
learning-room/ - Root level markdown files (README.md, CONTRIBUTING.md, etc.)
You can build HTML files locally to preview your changes before pushing:
# Install dependencies (first time only)
npm install
# Generate HTML files once
npm run build:html
# Watch mode - rebuilds HTML automatically when you save markdown files
npm run watch:html
# Clean generated HTML
npm run cleanGenerated HTML files will be in the html/ directory with the same folder structure as the source markdown files.
The generated documentation includes:
- GitHub-flavored styling - familiar appearance for GitHub users
- Syntax highlighting for code blocks
- Responsive design - works on mobile and desktop
- Accessible markup - proper ARIA labels, semantic HTML, keyboard navigation
- Breadcrumb navigation - easy to return to home
- High contrast mode support - respects user preferences
Build before committing:
After editing any .md file, run npm run build:html and include the updated html/ files in your commit. A typical commit workflow:
# Edit your .md files, then:
npm run build:html
git add -A
git commit -m "docs: update chapter 6 and rebuild HTML"Testing the HTML locally (optional): If you want to verify how your Markdown will look in HTML before committing:
- Run
npm install(first time only) - Run
npm run build:html - Open files in
html/directory in your browser
HTML files in the repository:
The html/ directory is committed to the repository so that:
- Documentation can be browsed directly from the repository
- HTML files are version-controlled alongside their Markdown source
- GitHub Pages can serve the documentation without a build step
"npm: command not found" You need to install Node.js first. Download from the Node.js download page (LTS version recommended).
Build errors:
- Ensure all markdown files have valid syntax
- Check that code blocks use proper fence syntax (
```) - Look for unclosed brackets or parentheses in links
If you are reviewing this repository using a screen reader, here are the relevant reading patterns.
- Table navigation:
Tto reach the table, thenCtrl+Alt+Arrow Keysto navigate cells - Code blocks are read as preformatted text. NVDA reads the content character-by-character if you need to copy a command - use
NVDA+F8to switch to flat review, thenNVDA+Cto copy a line - Headings:
Hto jump between headings when in browse mode
- Table navigation:
Tto reach the table,Ctrl+Alt+Arrow Keysfor cells - Code blocks:
Insert+F5(forms list) will not find code elements - navigate with cursor keys - Headings:
Hforward,Shift+Hbackward
- Table navigation:
VO+Right Arrowthrough rows,VO+Cmd+Right Arrowthrough columns - Code blocks in Markdown renderers on GitHub: navigate with
VO+Right Arrow; activate "Select All" (Cmd+A) then "Copy" (Cmd+C) to copy a block - Heading navigation with Rotor:
VO+U, then left-right to select "Headings", then up-down to navigate
When you open a pull request, fill in the template that appears. If no template appears, include:
## What does this change?
<!-- One or two sentences describing the change -->
## Why?
<!-- What problem does this fix or what gap does it address? -->
## How to test / review
<!-- What should a reviewer look at? Where is the change? -->
## Checklist
- [ ] Heading levels are in sequence (no skips)
- [ ] All links use descriptive text (no bare URLs in running text)
- [ ] Command examples are in fenced code blocks
- [ ] Tables have header rows
- [ ] Spelling and grammar reviewedfix: correct JAWS shortcut for PR review in Section 3
docs: add alternative macOS exercise for Section 6
exercise: add bonus challenge for notifications day 2
Small, focused pull requests are reviewed faster and merged sooner. If you have multiple unrelated improvements, submit them as separate pull requests.
- A maintainer reviews your PR - typically within a few days for documentation changes
- You may receive review comments - these are not rejections; they are part of the collaboration
- You can add commits to the same branch to respond to feedback - GitHub adds them to the open PR automatically
- Once approved, a maintainer will merge the PR
- Your name is in the commit history of the repository - that is the permanent record of your contribution
If two weeks pass with no response, feel free to leave a comment on the PR to check in.
Before opening an issue: Search existing issues and discussions to see whether the question has already been raised.
For documentation discussions: Open a GitHub Discussion (if enabled) or an Issue labeled question
For urgent issues with the workshop materials during a live event: Contact the facilitator directly
For accessibility concerns: Tag your issue or comment with the accessibility label
Workshops run better when participants contribute back. Every correction, every clarification, every additional exercise makes this material stronger for everyone who comes after you. Your name in the commit history is not the end of your participation - it is the beginning.