diff --git a/BATCH.md b/BATCH.md index b0eb1044..f066e371 100644 --- a/BATCH.md +++ b/BATCH.md @@ -18,7 +18,7 @@ Run operations in this sequence for a full podcast build from scratch: Validates the podcast catalog, builds episode and challenge bundles, then writes all episode and challenge coach scripts to `podcasts\scripts\`. -``` +```bat generate-transcripts.bat ``` @@ -38,7 +38,7 @@ The script echoes each episode name and index as it is processed. ffmpeg is required for MP3 output and is located automatically from the machine PATH, including after a fresh winget install. -``` +```text generate-audio.bat generate all 75 episodes generate-audio.bat 5 generate episodes 5 and above generate-audio.bat 5 10 generate episodes 5 through 10 @@ -54,7 +54,7 @@ before running this command. Generates the RSS 2.0 / iTunes-compatible podcast feed and the admin podcast listing. Reads MP3 file sizes from `podcasts\audio\` and episode metadata from the catalog. -``` +```bat build-rss-feed.bat ``` @@ -70,7 +70,7 @@ reflect the final MP3 file sizes. Runs local RSS 2.0 and iTunes compliance checks on `podcasts\feed.xml`. -``` +```bat validate-rss-feed.bat ``` @@ -114,7 +114,7 @@ a PowerShell or bash session at the repo root. To pass a range to the audio build from npm: -``` +```bash npm run build:podcast-audio -- --start 5 --end 10 ``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7272e8d7..b886a619 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -100,7 +100,7 @@ git remote -v Expected output: -``` +```text 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) @@ -164,7 +164,7 @@ which is not a term NVDA uses. Updated to match NVDA's own terminology." **Commit message format:** -``` +```text type: short summary (under 72 characters) Optional longer explanation of why the change was made, not just what @@ -402,7 +402,7 @@ When you open a pull request, fill in the template that appears. If no template ### PR Title Format -``` +```text fix: 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 diff --git a/README.md b/README.md index 35aff1de..53076280 100644 --- a/README.md +++ b/README.md @@ -96,7 +96,7 @@ You do **not** need to know how to code to participate and contribute meaningful This is not a two-day course with two separate syllabi. It is one arc. -``` +```text Day 1 - Learn the skill in the browser Navigate → Issue → Pull Request → Review → Merge @@ -233,7 +233,7 @@ Every chapter has an "If You Get Stuck" section. Every challenge has a [referenc > **One repository, everything included.** Clone or fork this repo and you have the complete workshop - all curriculum guides, Accessibility Agents agents and slash commands, YAML issue forms, PR template, and a practice contribution target in `learning-room/`. GitHub Skills modules cannot be bundled here (each participant activates their own copy on their own account), but links are in `.github/ISSUE_TEMPLATE/config.yml`. -``` +```text [repo root]/ ├── README.md -- You are here ├── CONTRIBUTING.md -- How to contribute to this repo diff --git a/admin/ACCESSIBILITY_TESTING.md b/admin/ACCESSIBILITY_TESTING.md index f3a8a712..dba96894 100644 --- a/admin/ACCESSIBILITY_TESTING.md +++ b/admin/ACCESSIBILITY_TESTING.md @@ -49,7 +49,7 @@ Use before deploying any new issue template or form. ### NVDA Testing (Windows) -``` +```text 1. Press NVDA+Space to enable browse mode on page 2. Press H to navigate to first heading 3. Use H repeatedly to scan all headings (should be H1 → H2 → H3, not jumps) @@ -73,7 +73,7 @@ Use before deploying any new issue template or form. ### JAWS Testing (Windows) -``` +```text 1. Press Spacebar to enter browse mode 2. Press Insert+F6 to open headings list - Verify headings are in order (1 → 2 → 3, no jumps) @@ -97,7 +97,7 @@ Use before deploying any new issue template or form. ### VoiceOver Testing (macOS) -``` +```text 1. Press VO+U to open Web Rotor 2. Navigate to Form Controls section - Should list all fields @@ -275,7 +275,7 @@ Test WITHOUT using the mouse. When you find an accessibility problem, document it: -``` +```text Title: [Accessibility] Form label missing on email field Description: diff --git a/admin/AGENTS_ROADMAP.md b/admin/AGENTS_ROADMAP.md index f7db30f6..ca1e6c4a 100644 --- a/admin/AGENTS_ROADMAP.md +++ b/admin/AGENTS_ROADMAP.md @@ -57,7 +57,7 @@ This document tracks the curriculum's alignment with Accessibility Agents versio **Example:** -``` +```text Version 4.x: User: @aria-specialist audit this component Agent: [Reports 3 ARIA errors] @@ -75,7 +75,7 @@ Agent: [Returns remediated code for approval] **Before (4.x):** No automated compliance reporting. **Now (5.0.0+):** Generate VPAT and compliance reports automatically. -``` +```text User: @document-csv-reporter generate-vpat audit-findings.json Agent: [Exports findings mapped to WCAG 2.2 AA and Section 508] Agent: [Generates VPAT template with compliance assertions] @@ -89,7 +89,7 @@ Output: compliance-report.xlsx **Capability:** -``` +```text Hook configuration: { "name": "continuous-eval", @@ -265,7 +265,7 @@ Output: Trend report showing score changes week-over-week ### Three Teams, 80 Agents, 5 Platforms -``` +```text Accessibility Agents 5.0.0 ├── Team 1: Accessibility (40 agents) │ ├── Web (26): Specialists, wizards, coaches diff --git a/admin/CURRICULUM_2.0_ORGANIZATION.md b/admin/CURRICULUM_2.0_ORGANIZATION.md index 5cabb8b3..5c2e87ae 100644 --- a/admin/CURRICULUM_2.0_ORGANIZATION.md +++ b/admin/CURRICULUM_2.0_ORGANIZATION.md @@ -12,22 +12,22 @@ | File | Type | Size | Status | |------|------|------|--------| -| `docs/appendix-aa-agent-installation-setup.md` | Reference guide | 1,200+ words | ✅ Complete | -| `docs/appendix-ab-advanced-agent-patterns.md` | Reference guide | 1,500+ words | ✅ Complete | -| `docs/appendix-ac-document-developer-tools.md` | Reference guide | 1,200+ words | ✅ Complete | -| `admin/AGENTS_ROADMAP.md` | Admin reference | 800+ words | ✅ Complete | +| `docs/appendix-aa-agent-installation-setup.md` | Reference guide | 1,200+ words | Complete | +| `docs/appendix-ab-advanced-agent-patterns.md` | Reference guide | 1,500+ words | Complete | +| `docs/appendix-ac-document-developer-tools.md` | Reference guide | 1,200+ words | Complete | +| `admin/AGENTS_ROADMAP.md` | Admin reference | 800+ words | Complete | ### Existing Files Modified (7) | File | Changes | Status | |------|---------|--------| -| `docs/00-pre-workshop-setup.md` | Added version requirements table | ✅ Complete | -| `docs/19-accessibility-agents.md` | Expanded intro, added section 3A, updated prerequisites | ✅ Complete | -| `docs/appendix-k-copilot-reference.md` | Added MCP Server section 4B | ✅ Complete | -| `docs/appendix-l-agents-reference.md` | Expanded to 80 agents, added skills, updated platforms | ✅ Complete | -| `.github/copilot-instructions.md` | Added agents-specific guidance section | ✅ Complete | -| `https://lp.csedesigns.com/ggg/PODCASTS.html` | Added episodes 41-43, regeneration notes | ✅ Complete | -| `admin/AGENTS_ROADMAP.md` | NEW file for agents tracking | ✅ Complete | +| `docs/00-pre-workshop-setup.md` | Added version requirements table | Complete | +| `docs/19-accessibility-agents.md` | Expanded intro, added section 3A, updated prerequisites | Complete | +| `docs/appendix-k-copilot-reference.md` | Added MCP Server section 4B | Complete | +| `docs/appendix-l-agents-reference.md` | Expanded to 80 agents, added skills, updated platforms | Complete | +| `.github/copilot-instructions.md` | Added agents-specific guidance section | Complete | +| `https://lp.csedesigns.com/ggg/PODCASTS.html` | Added episodes 41-43, regeneration notes | Complete | +| `admin/AGENTS_ROADMAP.md` | NEW file for agents tracking | Complete | **Total new content:** ~7,600 words | **Total files touched:** 11 @@ -39,27 +39,27 @@ **Links OUT to:** -- ✅ [Appendix L: Agents Reference](../docs/appendix-l-agents-reference.md) - "All 80 agents organized by team" -- ✅ [Appendix K: Copilot Reference](../docs/appendix-k-copilot-reference.md) - "Platform features and MCP" -- ✅ [Appendix M: Accessibility Standards](../docs/appendix-m-accessibility-standards.md) - "WCAG 2.2 AA reference" (existing) -- ✅ [Appendix AA: Installation & Setup](../docs/appendix-aa-agent-installation-setup.md) - "Platform-specific installation guide (NEW)" -- ✅ [Appendix AB: Advanced Patterns](../docs/appendix-ab-advanced-agent-patterns.md) - "Subagents, hooks, skills (NEW)" -- ✅ [Appendix AC: Document & Developer Tools](../docs/appendix-ac-document-developer-tools.md) - "Specialized agents (NEW)" -- ✅ [admin/AGENTS_ROADMAP.md](admin/AGENTS_ROADMAP.md) - "Version history and learning pathways (NEW)" +- [Appendix L: Agents Reference](../docs/appendix-l-agents-reference.md) - "All 80 agents organized by team" +- [Appendix K: Copilot Reference](../docs/appendix-k-copilot-reference.md) - "Platform features and MCP" +- [Appendix M: Accessibility Standards](../docs/appendix-m-accessibility-standards.md) - "WCAG 2.2 AA reference" (existing) +- [Appendix AA: Installation & Setup](../docs/appendix-aa-agent-installation-setup.md) - "Platform-specific installation guide (NEW)" +- [Appendix AB: Advanced Patterns](../docs/appendix-ab-advanced-agent-patterns.md) - "Subagents, hooks, skills (NEW)" +- [Appendix AC: Document & Developer Tools](../docs/appendix-ac-document-developer-tools.md) - "Specialized agents (NEW)" +- [admin/AGENTS_ROADMAP.md](admin/AGENTS_ROADMAP.md) - "Version history and learning pathways (NEW)" **Section 3A content includes:** -- ✅ Platform comparison table (5 platforms) -- ✅ Links to installation guide per platform -- ✅ Decision tree for platform selection -- ✅ Screen reader/low vision/keyboard guidance +- Platform comparison table (5 platforms) +- Links to installation guide per platform +- Decision tree for platform selection +- Screen reader/low vision/keyboard guidance **Learning cards include:** -- ✅ Screen reader workflow -- ✅ Low vision workflow -- ✅ Keyboard-only workflow -- ✅ Sighted mouse workflow +- Screen reader workflow +- Low vision workflow +- Keyboard-only workflow +- Sighted mouse workflow --- @@ -67,17 +67,17 @@ **Links OUT to:** -- ✅ [Appendix L: Agents Reference](../docs/appendix-l-agents-reference.md) - "Agent list and capabilities" -- ✅ [Appendix AA: Installation & Setup](../docs/appendix-aa-agent-installation-setup.md) - "Platform-specific setup" -- ✅ [Chapter 19: Accessibility Agents](../docs/19-accessibility-agents.md) - "Agent introduction" -- ✅ [admin/AGENTS_ROADMAP.md](admin/AGENTS_ROADMAP.md) - "Version tracking" +- [Appendix L: Agents Reference](../docs/appendix-l-agents-reference.md) - "Agent list and capabilities" +- [Appendix AA: Installation & Setup](../docs/appendix-aa-agent-installation-setup.md) - "Platform-specific setup" +- [Chapter 19: Accessibility Agents](../docs/19-accessibility-agents.md) - "Agent introduction" +- [admin/AGENTS_ROADMAP.md](admin/AGENTS_ROADMAP.md) - "Version tracking" **New Section 4B (MCP Servers) includes:** -- ✅ 30+ tools organized by category (web, document, markdown, compliance, CI/CD) -- ✅ Usage examples for each platform -- ✅ GitHub Actions CI/CD example with YAML -- ✅ Learning cards for all audience types +- 30+ tools organized by category (web, document, markdown, compliance, CI/CD) +- Usage examples for each platform +- GitHub Actions CI/CD example with YAML +- Learning cards for all audience types --- @@ -85,19 +85,19 @@ **Links OUT to:** -- ✅ [Appendix K: Copilot Reference](../docs/appendix-k-copilot-reference.md) - "Copilot features" -- ✅ [Chapter 19: Accessibility Agents](../docs/19-accessibility-agents.md) - "Agents introduction" -- ✅ [Appendix AA: Installation & Setup](../docs/appendix-aa-agent-installation-setup.md) - "Getting started" -- ✅ [Accessibility Agents Repository](https://github.com/Community-Access/accessibility-agents) - "Canonical source for 80 agents" +- [Appendix K: Copilot Reference](../docs/appendix-k-copilot-reference.md) - "Copilot features" +- [Chapter 19: Accessibility Agents](../docs/19-accessibility-agents.md) - "Agents introduction" +- [Appendix AA: Installation & Setup](../docs/appendix-aa-agent-installation-setup.md) - "Getting started" +- [Accessibility Agents Repository](https://github.com/Community-Access/accessibility-agents) - "Canonical source for 80 agents" **Updated tables include:** -- ✅ Team 1: 40 agents (26 web + 14 document) -- ✅ Team 2: 20 agents (GitHub Workflow) -- ✅ Team 3: 18 agents (Developer Tools) -- ✅ Platforms table with "When to Use" column -- ✅ Skills section (25+ bundled skills) -- ✅ MCP tools section (30+ tools) +- Team 1: 40 agents (26 web + 14 document) +- Team 2: 20 agents (GitHub Workflow) +- Team 3: 18 agents (Developer Tools) +- Platforms table with "When to Use" column +- Skills section (25+ bundled skills) +- MCP tools section (30+ tools) --- @@ -105,24 +105,24 @@ **Links OUT to:** -- ✅ [Appendix L: Agents Reference](../docs/appendix-l-agents-reference.md) - "All agents" -- ✅ [Chapter 19: Accessibility Agents](../docs/19-accessibility-agents.md) - "Agent overview" -- ✅ [Accessibility Agents Repository](https://github.com/Community-Access/accessibility-agents) - "Official source" +- [Appendix L: Agents Reference](../docs/appendix-l-agents-reference.md) - "All agents" +- [Chapter 19: Accessibility Agents](../docs/19-accessibility-agents.md) - "Agent overview" +- [Accessibility Agents Repository](https://github.com/Community-Access/accessibility-agents) - "Official source" **Platform-specific sections cover:** -- ✅ GitHub Copilot (VS Code) - section with detailed steps -- ✅ Claude Code - section with CLI setup -- ✅ Gemini CLI - section with free tier info -- ✅ Claude Desktop - section with MCP configuration -- ✅ Codex CLI - section with TOML setup +- GitHub Copilot (VS Code) - section with detailed steps +- Claude Code - section with CLI setup +- Gemini CLI - section with free tier info +- Claude Desktop - section with MCP configuration +- Codex CLI - section with TOML setup **Cross-platform guidance includes:** -- ✅ System requirements table -- ✅ Version checking commands -- ✅ Troubleshooting by platform -- ✅ Learning cards (SR/LV/keyboard/sighted) +- System requirements table +- Version checking commands +- Troubleshooting by platform +- Learning cards (SR/LV/keyboard/sighted) --- @@ -130,20 +130,20 @@ **Links OUT to:** -- ✅ [Appendix L: Agents Reference](../docs/appendix-l-agents-reference.md) - "Agent list" -- ✅ [Appendix AA: Installation & Setup](../docs/appendix-aa-agent-installation-setup.md) - "Setup reference" -- ✅ [Chapter 19: Accessibility Agents](../docs/19-accessibility-agents.md) - "Agent context" -- ✅ [Accessibility Agents Repository](https://github.com/Community-Access/accessibility-agents) - "Source for skills and hooks" +- [Appendix L: Agents Reference](../docs/appendix-l-agents-reference.md) - "Agent list" +- [Appendix AA: Installation & Setup](../docs/appendix-aa-agent-installation-setup.md) - "Setup reference" +- [Chapter 19: Accessibility Agents](../docs/19-accessibility-agents.md) - "Agent context" +- [Accessibility Agents Repository](https://github.com/Community-Access/accessibility-agents) - "Source for skills and hooks" **Advanced topics covered:** -- ✅ Subagent delegation with examples -- ✅ Skills (25+ library overview) -- ✅ Hooks (lifecycle automation) with JSON examples -- ✅ Browser tools catalog -- ✅ Orchestration patterns -- ✅ Custom skills authoring -- ✅ Continuous evaluation setup +- Subagent delegation with examples +- Skills (25+ library overview) +- Hooks (lifecycle automation) with JSON examples +- Browser tools catalog +- Orchestration patterns +- Custom skills authoring +- Continuous evaluation setup --- @@ -151,19 +151,19 @@ **Links OUT to:** -- ✅ [Appendix L: Agents Reference](../docs/appendix-l-agents-reference.md) - "Complete agent list" -- ✅ [Appendix AB: Advanced Patterns](../docs/appendix-ab-advanced-agent-patterns.md) - "Advanced techniques" -- ✅ [Appendix AA: Installation & Setup](../docs/appendix-aa-agent-installation-setup.md) - "Setup guide" +- [Appendix L: Agents Reference](../docs/appendix-l-agents-reference.md) - "Complete agent list" +- [Appendix AB: Advanced Patterns](../docs/appendix-ab-advanced-agent-patterns.md) - "Advanced techniques" +- [Appendix AA: Installation & Setup](../docs/appendix-aa-agent-installation-setup.md) - "Setup guide" **Specialized content covers:** -- ✅ 15 document agents (Word, Excel, PowerPoint, PDF, EPUB) -- ✅ Office accessibility patterns with common issues/fixes -- ✅ PDF/UA standard compliance -- ✅ 8 developer tools agents (Python, wxPython, CI/CD, desktop) -- ✅ Code examples for accessible Python and wxPython -- ✅ NVDA add-on development overview -- ✅ CI/CD accessibility integration +- 15 document agents (Word, Excel, PowerPoint, PDF, EPUB) +- Office accessibility patterns with common issues/fixes +- PDF/UA standard compliance +- 8 developer tools agents (Python, wxPython, CI/CD, desktop) +- Code examples for accessible Python and wxPython +- NVDA add-on development overview +- CI/CD accessibility integration --- @@ -171,10 +171,10 @@ **New section: Version Requirements** -- ✅ Minimum versions table (VS Code 1.113+, Node.js v18+, Git v2.20+) -- ✅ Version checking commands -- ✅ Links to [Appendix AA: Installation](../docs/appendix-aa-agent-installation-setup.md) -- ✅ Explains agents are optional (Day 2 extension) +- Minimum versions table (VS Code 1.113+, Node.js v18+, Git v2.20+) +- Version checking commands +- Links to [Appendix AA: Installation](../docs/appendix-aa-agent-installation-setup.md) +- Explains agents are optional (Day 2 extension) --- @@ -182,15 +182,15 @@ **New section: Agents & Accessibility Patterns** -- ✅ Agent reference formatting rules (`` `@agent-name` ``) -- ✅ Platform support documentation requirements -- ✅ Prerequisite clarity guidelines -- ✅ Multi-workflow documentation pattern (SR/LV/keyboard/sighted) -- ✅ Skill-first principle preservation -- ✅ Podcast regeneration tracking -- ✅ Cross-platform considerations -- ✅ Common mistakes table -- ✅ References section with links to all appendices +- Agent reference formatting rules (`` `@agent-name` ``) +- Platform support documentation requirements +- Prerequisite clarity guidelines +- Multi-workflow documentation pattern (SR/LV/keyboard/sighted) +- Skill-first principle preservation +- Podcast regeneration tracking +- Cross-platform considerations +- Common mistakes table +- References section with links to all appendices --- @@ -198,12 +198,12 @@ **New sections added:** -- ✅ Episodes 41-43: Agents content (new appendices AA, AB, AC) -- ✅ Episodes pending regeneration (17, 39, 40) -- ✅ Recording checklist for all episodes -- ✅ Production notes for recording team -- ✅ Quality assurance checklist -- ✅ Alex & Jamie style guide reference +- Episodes 41-43: Agents content (new appendices AA, AB, AC) +- Episodes pending regeneration (17, 39, 40) +- Recording checklist for all episodes +- Production notes for recording team +- Quality assurance checklist +- Alex & Jamie style guide reference --- @@ -211,14 +211,14 @@ **Organization reference includes:** -- ✅ Version alignment table (Curriculum 2.0 ↔ Agents 5.0.0+) -- ✅ Capability matrix (8 features in 5.0+) -- ✅ Key transitions (4.x → 5.0.0) -- ✅ 4 learning pathways (Web, Document, Developer Tools, Multi-Platform) -- ✅ Contribution guidance for facilitators -- ✅ Infrastructure overview (80 agents, 5 platforms, 25+ skills) -- ✅ Roadmap for future versions -- ✅ Maintenance tasks by semester +- Version alignment table (Curriculum 2.0 with Agents 5.0.0+) +- Capability matrix (8 features in 5.0+) +- Key transitions (4.x → 5.0.0) +- 4 learning pathways (Web, Document, Developer Tools, Multi-Platform) +- Contribution guidance for facilitators +- Infrastructure overview (80 agents, 5 platforms, 25+ skills) +- Roadmap for future versions +- Maintenance tasks by semester --- @@ -296,22 +296,22 @@ All new files include **learning cards** with four workflow perspectives: | Workflow | Included in All New Files | Example | |----------|--------------------------|---------| -| Screen reader users | ✅ | "Use `H` key to navigate section headings" | -| Low vision users | ✅ | "Zoom in on the table independently with Ctrl+=" | -| Keyboard-only users | ✅ | "Tab through controls; use Enter to activate" | -| Sighted users | ✅ | "Use visual hierarchy to scan sections quickly" | +| Screen reader users | Yes | "Use `H` key to navigate section headings" | +| Low vision users | Yes | "Zoom in on the table independently with Ctrl+=" | +| Keyboard-only users | Yes | "Tab through controls; use Enter to activate" | +| Sighted users | Yes | "Use visual hierarchy to scan sections quickly" | **Validation status:** -- ✅ Appendix AA: 4 learning cards (SR, LV, Keyboard, Sighted) -- ✅ Appendix AB: 3 learning cards (SR, LV, Sighted) + workflow diagrams -- ✅ Appendix AC: 3 learning cards (SR, LV, Sighted) + tables -- ✅ Chapter 19 Section 3A: Platform-specific accessibility notes -- ✅ Chapter 0: Version requirements clearly stated +- Appendix AA: 4 learning cards (SR, LV, Keyboard, Sighted) +- Appendix AB: 3 learning cards (SR, LV, Sighted) + workflow diagrams +- Appendix AC: 3 learning cards (SR, LV, Sighted) + tables +- Chapter 19 Section 3A: Platform-specific accessibility notes +- Chapter 0: Version requirements clearly stated -**No emojis used:** ✅ All files (consistent with curriculum style) +**No emojis used:** Yes, all files (consistent with curriculum style) -**Descriptive links throughout:** ✅ All cross-references specific and tested +**Descriptive links throughout:** Yes, all cross-references specific and tested --- @@ -335,11 +335,11 @@ All new files include **learning cards** with four workflow perspectives: **Recording prerequisites met:** -- ✅ All content written and formatted -- ✅ Alex & Jamie style guide available (PODCASTS.md) -- ✅ Learning cards prepared for each episode -- ✅ Production checklist ready () -- ✅ Quality assurance steps documented +- All content written and formatted +- Alex & Jamie style guide available (PODCASTS.md) +- Learning cards prepared for each episode +- Production checklist ready () +- Quality assurance steps documented --- @@ -390,12 +390,12 @@ All new files include **learning cards** with four workflow perspectives: | Podcast episodes new/regenerated | 6 (3 new + 3 regenerated) | | Estimated podcast recording time | 120+ minutes | | Cross-references verified | 100% | -| Accessibility validation | ✅ Complete (SR, LV, keyboard, sighted) | -| No emojis used | ✅ Confirmed | +| Accessibility validation | Complete (SR, LV, keyboard, sighted) | +| No emojis used | Confirmed | --- -**All Priority 1-5 tasks complete. Curriculum 2.0 ready for production.** ✅ +**All Priority 1-5 tasks complete. Curriculum 2.0 ready for production.** ## Authoritative Sources diff --git a/admin/DAY2_AGENDA.md b/admin/DAY2_AGENDA.md index 774e7db3..b7ec7e77 100644 --- a/admin/DAY2_AGENDA.md +++ b/admin/DAY2_AGENDA.md @@ -437,7 +437,7 @@ If you did not finish your commit during Block 2, use the first 15 minutes of th Before opening the PR, run through this with your screen reader: -``` +```text □ My branch has a clear descriptive name (feature/, fix/, or docs/) □ I committed with a clear, present-tense message □ I read my changes back using VS Code's diff view (Ctrl+Shift+G → select file) diff --git a/admin/FACILITATOR_CHALLENGES.md b/admin/FACILITATOR_CHALLENGES.md index 03520ebf..31947faf 100644 --- a/admin/FACILITATOR_CHALLENGES.md +++ b/admin/FACILITATOR_CHALLENGES.md @@ -182,13 +182,13 @@ The Progression Bot applies these labels to each challenge issue it creates: ### Issue Title Convention -``` +```text Challenge [NUMBER]: [Title] ``` Examples: -``` +```text Challenge 1: Find Your Way Around Challenge 7: Resolve a Merge Conflict Challenge 16: Build Your Agent diff --git a/admin/FACILITATOR_GUIDE.md b/admin/FACILITATOR_GUIDE.md index 41e59cf5..61d79c50 100644 --- a/admin/FACILITATOR_GUIDE.md +++ b/admin/FACILITATOR_GUIDE.md @@ -6,11 +6,11 @@ This is your comprehensive guide to facilitate a two-day GitHub workshop. It cov --- -## 🎯 Quick Navigation +## Quick Navigation -- **Just starting?** → Go to [GitHub Classroom Setup](#-github-classroom-setup-before-day-1) -- **Workshop is tomorrow?** → Go to [Pre-Workshop Checklist](#-pre-workshop-checklist-48-hours-before) -- **Workshop is happening now?** → Go to [Live Workshop Operations](#-day-1-live-operations) +- **Just starting?** → Go to [GitHub Classroom Setup](#github-classroom-setup-before-day-1) +- **Workshop is tomorrow?** → Go to [Pre-Workshop Checklist](#pre-workshop-checklist-48-hours-before) +- **Workshop is happening now?** → Go to [Live Workshop Operations](#day-1-live-operations) - **Student got stuck?** → Go to [Troubleshooting Guide](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md) - **Need hands-on details?** → Go to [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md) @@ -36,7 +36,7 @@ This is your comprehensive guide to facilitate a two-day GitHub workshop. It cov --- -## 👥 Your Facilitation Team +## Your Facilitation Team This workshop is designed for **2 co-facilitators** who can split roles: @@ -51,9 +51,9 @@ If you're solo: --- -## 🚀 GitHub Classroom Setup (Before Day 1) +## GitHub Classroom Setup (Before Day 1) -This section is for someone (probably you!) setting up GitHub Classroom for the first time. If your Classroom is already configured, skip to [Pre-Workshop Checklist](#-pre-workshop-checklist-48-hours-before). +This section is for someone (probably you!) setting up GitHub Classroom for the first time. If your Classroom is already configured, skip to [Pre-Workshop Checklist](#pre-workshop-checklist-48-hours-before). ### What is GitHub Classroom? @@ -124,9 +124,9 @@ Save both invite links in a safe place (notes, email yourself, password manager) - Merging closes the issue - Next challenge issue appears -If anything is missing, see [Troubleshooting GitHub Classroom Setup](#troubleshooting-github-classroom-setup) below. +If anything is missing, see [Known Gotchas](#known-gotchas) below. -### ⚠️ Known Gotchas +### Known Gotchas **"The invite link isn't working"** @@ -154,7 +154,7 @@ If anything is missing, see [Troubleshooting GitHub Classroom Setup](#troublesho --- -## 📋 Pre-Workshop Checklist (48 Hours Before) +## Pre-Workshop Checklist (48 Hours Before) You have two days until the workshop. Use this checklist: @@ -198,11 +198,11 @@ You have two days until the workshop. Use this checklist: - Video call has tech issues (phone dial-in number active) - Bot stops working (you'll manually review PRs) - Key facilitator unavailable (co-facilitator can lead) -- [ ] Coffee/water ready 😄 +- [ ] Coffee/water ready --- -## ✨ Day 1: Live Operations +## Day 1: Live Operations This section covers what you and your co-facilitator do during Day 1. @@ -341,7 +341,7 @@ When you notice something: - Comment if needed: "Looking good! I see the bot asked you to [X]. Give that a try!" 3. **Student merged a PR** → Celebrate publicly: - > "🎉 Awesome work @student! You just merged your first pull request! That's huge." + > "Awesome work @student! You just merged your first pull request! That's huge." 4. **Gandalf bot gave confusing feedback** → Translate it: > "I see Gandalf's feedback. Let me explain what it means: [plain language explanation]. Try [specific fix]." @@ -438,7 +438,7 @@ Pull from the Classroom dashboard: --- -## 🎉 Day 2: Deeper Skills and Celebration +## Day 2: Deeper Skills and Celebration ### Hour 1: Recap and Momentum (30 min) @@ -498,7 +498,7 @@ Pull from the Classroom dashboard: 1. Assign pairs: "Student A, you review Student B's PR. Student B, you'll review Student C's. Etc." 2. Give them a template for feedback: - ``` + ```text - What I liked about this PR: [specific thing] - One question I have: [genuine question] - One suggestion: [improvement idea] @@ -643,7 +643,7 @@ Point to: --- -## 📊 Post-Workshop Tasks (Week After) +## Post-Workshop Tasks (Week After) ### Day 3 (Next Day) @@ -685,7 +685,7 @@ Point to: --- -## 🆘 Quick Troubleshooting Reference +## Quick Troubleshooting Reference ### During Workshop @@ -716,7 +716,7 @@ For more, see [FACILITATOR_CLASSROOM_TROUBLESHOOTING.md](FACILITATOR_CLASSROOM_T --- -## 📚 Appendices +## Appendices ### Appendix A: Facilitator Communication Templates @@ -813,7 +813,7 @@ Subject: Your GitHub Workshop Starts Tomorrow! *These are used in each challenge issue. Paste them into challenge issues to guide stuck students:* **For editing challenges:** -> If you get stuck: Look for the pencil icon (✏️) to edit the file. Type your change, then scroll down and click "Propose changes." +> If you get stuck: Select the pencil icon, the "Edit this file" button, to edit the file. Type your change, then scroll down and click "Propose changes." **For PR challenges:** > If you get stuck: Don't refresh the page yet! GitHub is still processing. Wait 30 seconds. If still nothing, paste this link in chat: [direct link to PR] @@ -826,7 +826,7 @@ Subject: Your GitHub Workshop Starts Tomorrow! --- -## 💡 Philosophy and Final Thoughts +## Philosophy and Final Thoughts This workshop succeeds because of **you** — the facilitator. Here's what you bring: @@ -845,13 +845,13 @@ That's the real goal. Everything else follows from that. --- -## 📞 Need Help? +## Need Help? If something goes wrong: 1. **Automation failing?** → See [FACILITATOR_CLASSROOM_TROUBLESHOOTING.md](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md) 2. **Student having issues?** → See [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md) -3. **Setting up for first time?** → Scroll back to [GitHub Classroom Setup](#-github-classroom-setup-before-day-1) +3. **Setting up for first time?** → Scroll back to [GitHub Classroom Setup](#github-classroom-setup-before-day-1) 4. **Can't find what you need?** → Email or ping us — we'll help and update this guide --- @@ -870,15 +870,15 @@ Use these official references when you need the current source of truth for fact Use this map to verify facts for each major section in this file. - **Running GitHub Classroom Workshops for Blind and Low-Vision Students:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/), [About Git](https://docs.github.com/en/get-started/using-git/about-git), [GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow), [About pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -- **🎯 Quick Navigation:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Quick Navigation:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) - **About This Workshop:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) -- **👥 Your Facilitation Team:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) -- **🚀 GitHub Classroom Setup (Before Day 1):** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/), [About Git](https://docs.github.com/en/get-started/using-git/about-git), [GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow), [About pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -- **📋 Pre-Workshop Checklist (48 Hours Before):** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) -- **✨ Day 1: Live Operations:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) -- **🎉 Day 2: Deeper Skills and Celebration:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/), [GitHub Skills catalog](https://skills.github.com/), [GitHub Learning Pathways](https://resources.github.com/learn/pathways/) -- **📊 Post-Workshop Tasks (Week After):** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) -- **🆘 Quick Troubleshooting Reference:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) -- **📚 Appendices:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) -- **💡 Philosophy and Final Thoughts:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) -- **📞 Need Help?:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Your Facilitation Team:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **GitHub Classroom Setup (Before Day 1):** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/), [About Git](https://docs.github.com/en/get-started/using-git/about-git), [GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow), [About pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) +- **Pre-Workshop Checklist (48 Hours Before):** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Day 1: Live Operations:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Day 2: Deeper Skills and Celebration:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/), [GitHub Skills catalog](https://skills.github.com/), [GitHub Learning Pathways](https://resources.github.com/learn/pathways/) +- **Post-Workshop Tasks (Week After):** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Quick Troubleshooting Reference:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Appendices:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Philosophy and Final Thoughts:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Need Help?:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) diff --git a/admin/FACILITATOR_OPERATIONS.md b/admin/FACILITATOR_OPERATIONS.md index 0026428d..027fc1e6 100644 --- a/admin/FACILITATOR_OPERATIONS.md +++ b/admin/FACILITATOR_OPERATIONS.md @@ -86,8 +86,8 @@ Ask GitHub or chat platform to notify you of: 1. **Welcome message to chat:** - ``` - Welcome to the GitHub Workshop! 👋 + ```text + Welcome to the GitHub Workshop! If you can see this message, you're connected. Video or audio-only? Both are fine. Screen reader users: All of GitHub.com is accessible. @@ -139,7 +139,7 @@ Ask GitHub or chat platform to notify you of: In chat, post: -``` +```text Here's your Day 1 invite link: [PASTE YOUR INVITE LINK] @@ -157,7 +157,7 @@ Accept and GitHub creates your repo. In chat as things happen: -``` +```text Great! I see people accepting the invite. You should now be in your private repo. Look for "Challenge 1" in your Issues tab. @@ -183,7 +183,7 @@ Wait until 70%+ have said they see Challenge 1 before moving forward. 1. **Open your test repo on screen** 2. **Narrate what you're doing:** - ``` + ```text "I'm going to show you what Challenge 1 looks like. I'm clicking the Issues tab... I see Challenge 1 here... @@ -219,7 +219,7 @@ Wait for confirmations. Help anyone who sees something different. > I need to edit a file called [filename]. Let me look in the file list... there it is. > > **Step 3: Click edit** -> I'm clicking the pencil icon (✏️) to edit the file. +> I'm selecting the pencil icon, the "Edit this file" button, to edit the file. > > **Step 4: Make my change** > [Type while narrating] I'm adding this text... done. @@ -312,7 +312,7 @@ Answer a few questions, then: - First merges happening - New challenges appearing -- Celebrate: "🎉 @student1 just merged their first PR! Nice work!" +- Celebrate: "@student1 just merged their first PR! Nice work!" **60-120 min:** @@ -338,7 +338,7 @@ Answer a few questions, then: |---|---| | "I'm stuck" | "Tell me what challenge you're on and what's confusing." (Then see troubleshooting guide) | | "Is this right?" | "What did you create? Show me a link." (Then validate) | -| "I merged!" | "🎉 Awesome! You just merged your first PR! That's huge!" | +| "I merged!" | "Awesome! You just merged your first PR! That's huge!" | | "What's next?" | "Your next challenge should appear soon. Refresh your Issues. If not, let me know!" | | "Is [technology] important?" | "Great question! [Short answer]. Let's talk more after this challenge." | | "My screen reader glitched" | "Which screen reader? What glitched? Let's fix it." (Then escalate if needed) | diff --git a/admin/FACILITATOR_RESOURCES.md b/admin/FACILITATOR_RESOURCES.md index 6330e1d5..271656a3 100644 --- a/admin/FACILITATOR_RESOURCES.md +++ b/admin/FACILITATOR_RESOURCES.md @@ -6,21 +6,21 @@ Welcome, facilitator! This page helps you navigate all the documentation for run --- -## 🎯 Start Here Based on Your Situation +## Start Here Based on Your Situation ### "I've Never Run This Workshop Before" → Read in this order: -1. [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-github-classroom-setup-before-day-1) — GitHub Classroom Setup section -2. [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-pre-workshop-checklist-48-hours-before) — Pre-Workshop Checklist +1. [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#github-classroom-setup-before-day-1) — GitHub Classroom Setup section +2. [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#pre-workshop-checklist-48-hours-before) — Pre-Workshop Checklist 3. [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md) — For hands-on procedures ### "Workshop Is Tomorrow" → Quick tasks: -1. [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-pre-workshop-checklist-48-hours-before) — Pre-Workshop Checklist (all boxes) +1. [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#pre-workshop-checklist-48-hours-before) — Pre-Workshop Checklist (all boxes) 2. [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md#pre-workshop-setup-3-hours-before) — 3-Hour Prep 3. [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md#starting-day-1-15-minutes-before-call-starts) — Day-Of Checklist @@ -43,18 +43,18 @@ Welcome, facilitator! This page helps you navigate all the documentation for run → Check: - [FACILITATOR_CLASSROOM_TROUBLESHOOTING.md](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md#-emergency-what-to-do-when-everything-stops-working) — Emergency protocols -- Then [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-quick-troubleshooting-reference) — Quick reference +- Then [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#quick-troubleshooting-reference) — Quick reference ### "Workshop Just Ended, What's Next?" → See: -- [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-post-workshop-tasks-week-after) — Post-workshop tasks +- [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#post-workshop-tasks-week-after) — Post-workshop tasks - [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md#post-workshop-operations) — Detailed post-workshop procedures --- -## 📚 Complete Resource Reference +## Complete Resource Reference ### Primary Documents @@ -159,17 +159,17 @@ Assessment rubric and grading guidance (brief reference). --- -## 🎓 Typical Workflow +## Typical Workflow ### Weeks 1-2 Before Workshop -1. Read [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-github-classroom-setup-before-day-1) GitHub Classroom Setup +1. Read [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#github-classroom-setup-before-day-1) GitHub Classroom Setup 2. Create your GitHub Classroom and assignments -3. Follow setup checklist in [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-pre-workshop-checklist-48-hours-before) +3. Follow setup checklist in [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#pre-workshop-checklist-48-hours-before) ### 48 Hours Before -1. Complete [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-pre-workshop-checklist-48-hours-before) checklist +1. Complete [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#pre-workshop-checklist-48-hours-before) checklist 2. Test everything one more time 3. Read [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md) overview @@ -183,22 +183,22 @@ Assessment rubric and grading guidance (brief reference). 1. Follow [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md) hour-by-hour 2. Keep [FACILITATOR_CLASSROOM_TROUBLESHOOTING.md](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md) open in another tab -3. Reference [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-day-1-live-operations) for overview +3. Reference [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#day-1-live-operations) for overview ### Day 2 During -1. Same as Day 1, but reference [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-day-2-deeper-skills-and-celebration) Day 2 section +1. Same as Day 1, but reference [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#day-2-deeper-skills-and-celebration) Day 2 section 2. Be ready for harder scenarios and more independence from students ### After Workshop -1. Follow [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-post-workshop-tasks-week-after) post-workshop tasks +1. Follow [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#post-workshop-tasks-week-after) post-workshop tasks 2. Note what worked and what didn't 3. Update this guide for next time --- -## 🔧 How to Use These Documents +## How to Use These Documents ### During Workshop: Have These Open @@ -237,7 +237,7 @@ Then search for: --- -## 📊 Document Overview at a Glance +## Document Overview at a Glance | Document | Purpose | Length | Best For | |----------|---------|--------|----------| @@ -249,7 +249,7 @@ Then search for: --- -## 🎯 Key Principles Across All Documents +## Key Principles Across All Documents These principles appear repeatedly because they're **that important**: @@ -263,7 +263,7 @@ These principles appear repeatedly because they're **that important**: --- -## 💡 Pro Tips from Experienced Facilitators +## Pro Tips from Experienced Facilitators - **Bookmark the documents** — You'll reference them constantly - **Add your own notes** — Margin notes about what worked for you @@ -276,7 +276,7 @@ These principles appear repeatedly because they're **that important**: --- -## 🚀 Related Resources +## Related Resources **In this repository:** @@ -292,7 +292,7 @@ These principles appear repeatedly because they're **that important**: --- -## ✅ Pre-Workshop Sanity Check +## Pre-Workshop Sanity Check Before your first workshop, verify: @@ -313,7 +313,7 @@ Before your first workshop, verify: --- -## 📞 Questions or Feedback? +## Questions or Feedback? Found an error or unclear section? Help improve this guide: @@ -342,13 +342,13 @@ Use these official references when you need the current source of truth for fact Use this map to verify facts for each major section in this file. - **Complete Guide to Running GitHub Classroom Workshops:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/), [About Git](https://docs.github.com/en/get-started/using-git/about-git), [GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow), [About pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -- **🎯 Start Here Based on Your Situation:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) -- **📚 Complete Resource Reference:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) -- **🎓 Typical Workflow:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/), [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax), [Secure use reference for GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions), [GitHub Actions changelog](https://github.blog/changelog/label/actions/) -- **🔧 How to Use These Documents:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) -- **📊 Document Overview at a Glance:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) -- **🎯 Key Principles Across All Documents:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) -- **💡 Pro Tips from Experienced Facilitators:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) -- **🚀 Related Resources:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) -- **✅ Pre-Workshop Sanity Check:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) -- **📞 Questions or Feedback?:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Start Here Based on Your Situation:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Complete Resource Reference:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Typical Workflow:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/), [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax), [Secure use reference for GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions), [GitHub Actions changelog](https://github.blog/changelog/label/actions/) +- **How to Use These Documents:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Document Overview at a Glance:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Key Principles Across All Documents:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Pro Tips from Experienced Facilitators:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Related Resources:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Pre-Workshop Sanity Check:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) +- **Questions or Feedback?:** [GitHub Docs, home](https://docs.github.com/en), [GitHub Changelog](https://github.blog/changelog/) diff --git a/admin/FAQ.md b/admin/FAQ.md index 97748b1b..abb59397 100644 --- a/admin/FAQ.md +++ b/admin/FAQ.md @@ -536,7 +536,7 @@ Full reference: [Appendix E (GitHub Flavored Markdown)](../docs/appendix-c-markd **A:** Wrap code in triple backticks. Add a language name for syntax highlighting: -```` +````markdown ```python print("Hello, world!") ``` @@ -546,7 +546,7 @@ print("Hello, world!") **A:** -``` +```markdown | Column 1 | Column 2 | |----------|----------| | Cell 1 | Cell 2 | diff --git a/admin/GITHUB_PROPOSAL.md b/admin/GITHUB_PROPOSAL.md index 3b79e13d..ddf0b766 100644 --- a/admin/GITHUB_PROPOSAL.md +++ b/admin/GITHUB_PROPOSAL.md @@ -229,7 +229,7 @@ Result: Users understand when agent output is correct or needs editing. Every exercise follows progression: -``` +```text Manual Skill (User does 100% by hand) ↓ With Agent (User does 50%, agent does 50%) @@ -269,7 +269,7 @@ Accessibility is woven into every chapter. ### File Structure -``` +```text .github/ ├── agents/ │ ├── daily-briefing.agent.md diff --git a/admin/QUICK_REFERENCE.md b/admin/QUICK_REFERENCE.md index 5f72a9d1..22e1075f 100644 --- a/admin/QUICK_REFERENCE.md +++ b/admin/QUICK_REFERENCE.md @@ -117,7 +117,7 @@ git fetch upstream # Fetch without merging ### Template & Agent Files -``` +```text .github/ ├── ISSUE_TEMPLATE/ │ ├── accessibility-bug.yml ← Accessibility issue template @@ -142,7 +142,7 @@ git fetch upstream # Fetch without merging ### Documentation Files -``` +```text docs/ ├── 00-pre-workshop-setup.md ← Start here ├── 02-understanding-github.md diff --git a/admin/README.md b/admin/README.md index fcf48c89..1b243a66 100644 --- a/admin/README.md +++ b/admin/README.md @@ -92,7 +92,7 @@ This folder contains all administrative and facilitator documentation for runnin ### Pre-Workshop (48 Hours Before) -1. [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-pre-workshop-checklist-48-hours-before) - Complete checklist +1. [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#pre-workshop-checklist-48-hours-before) - Complete checklist 2. [ACCESSIBILITY_TESTING.md](ACCESSIBILITY_TESTING.md) - Test with screen readers 3. [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md#pre-workshop-setup-3-hours-before) - Setup workstation @@ -104,7 +104,7 @@ This folder contains all administrative and facilitator documentation for runnin ### Post-Workshop -1. [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-post-workshop-tasks-week-after) - Follow-up tasks +1. [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#post-workshop-tasks-week-after) - Follow-up tasks 2. Update this documentation with lessons learned --- @@ -121,7 +121,7 @@ This folder contains all administrative and facilitator documentation for runnin ### For Returning Facilitators 1. Quick reference: [QUICK_REFERENCE.md](QUICK_REFERENCE.md) -2. Review: [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-pre-workshop-checklist-48-hours-before) checklist +2. Review: [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#pre-workshop-checklist-48-hours-before) checklist 3. Keep open: [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md) during workshop ### For Admin/Coordinators @@ -137,7 +137,7 @@ This folder contains all administrative and facilitator documentation for runnin ### GitHub Classroom -- [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-github-classroom-setup-before-day-1) - Complete setup +- [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#github-classroom-setup-before-day-1) - Complete setup - [COHORT_PROVISIONING.md](COHORT_PROVISIONING.md) - Provisioning - [classroom/README.md](classroom/README.md) - Fast copy-paste setup pack diff --git a/admin/TROUBLESHOOTING.md b/admin/TROUBLESHOOTING.md index 8c1128fb..931e6101 100644 --- a/admin/TROUBLESHOOTING.md +++ b/admin/TROUBLESHOOTING.md @@ -271,7 +271,7 @@ See [Appendix D (Git Authentication)](../docs/appendix-d-git-authentication.md) Then add to `~/.ssh/config`: - ``` + ```text Host github.com AddKeysToAgent yes UseKeychain yes diff --git a/admin/classroom admin access.md b/admin/classroom admin access.md index 17c13bc7..dbf994f9 100644 --- a/admin/classroom admin access.md +++ b/admin/classroom admin access.md @@ -1,3 +1,7 @@ +# GitHub Classroom Admin Access + +Facilitators with admin access manage the workshop classroom at this address: + ## Authoritative Sources diff --git a/admin/planning/SHIP-CHECKLIST.md b/admin/planning/SHIP-CHECKLIST.md index ceaaf30e..9c2c9c94 100644 --- a/admin/planning/SHIP-CHECKLIST.md +++ b/admin/planning/SHIP-CHECKLIST.md @@ -25,7 +25,7 @@ away. ## Dry-run summary -``` +```text Stage 3.1 - rename plan 58 mp3 renames (e.g. ch-00-welcome.mp3 -> ch-00-welcome.mp3) 21 no-op (current_filename == filename) diff --git a/admin/planning/SITE-IA.md b/admin/planning/SITE-IA.md index 83b337ff..d0369cdd 100644 --- a/admin/planning/SITE-IA.md +++ b/admin/planning/SITE-IA.md @@ -240,7 +240,7 @@ The generator runs axe-core in CI on a representative sample (homepage, one band ## Routing summary (one-screen reference) -``` +```text / home /learn/ curriculum view (interleaved) /feed-order/ strict track_number list diff --git a/docs/05-working-with-issues.md b/docs/05-working-with-issues.md index 28f3487d..f5bef450 100644 --- a/docs/05-working-with-issues.md +++ b/docs/05-working-with-issues.md @@ -299,7 +299,7 @@ Navigate directly: `https://github.com/[owner]/[repo]/issues` ### Page structure -``` +```text [Search / filter bar] -- controls at the top [State tabs: Open / Closed] -- filter by status [Issues list] -- each issue is one list item or heading diff --git a/docs/07-merge-conflicts.md b/docs/07-merge-conflicts.md index 941f356d..77a965ab 100644 --- a/docs/07-merge-conflicts.md +++ b/docs/07-merge-conflicts.md @@ -416,7 +416,7 @@ The content coming from the OTHER branch (or main) #### After two students both added a shortcut to the same table row -``` +```text <<<<<<< HEAD Insert+Space -- Toggle between Browse Mode and Focus Mode Insert+F5 -- List elements by type @@ -580,7 +580,7 @@ VS Code has excellent merge conflict tooling with full screen reader support. Th ### VS Code shows conflicts as -``` +```text <<<<<<< HEAD (Current Change) Your version ======= original -- (3-way merge, if enabled) diff --git a/docs/15-code-review.md b/docs/15-code-review.md index f7e28fe7..4787d692 100644 --- a/docs/15-code-review.md +++ b/docs/15-code-review.md @@ -1425,7 +1425,7 @@ Each file's diff is a table. Every row is one line of code.
Screen reader users - NVDA -``` +```text Press T to jump to the diff table then Insert+Space (Focus Mode) Press Down Arrow to move through lines one at a time Press Ctrl+Alt+Right Arrow to read across columns: line number, change type, code content @@ -1436,7 +1436,7 @@ Press Ctrl+Alt+Right Arrow to read across columns: line number, change type, cod
Screen reader users - JAWS -``` +```text Press T to jump to the diff table then Insert+Z (Virtual PC Cursor off) Press Down Arrow to move through lines Press Ctrl+Alt+Right Arrow for column-by-column reading @@ -1447,7 +1447,7 @@ Press Ctrl+Alt+Right Arrow for column-by-column reading
Screen reader users - VoiceOver (macOS) -``` +```text Press T or VO+U then Tables then select the diff table VO+Shift+Down Arrow to enter the table VO+Right/Left to navigate columns, VO+Up/Down to navigate rows diff --git a/docs/16-github-copilot.md b/docs/16-github-copilot.md index f5ad0715..318df4f5 100644 --- a/docs/16-github-copilot.md +++ b/docs/16-github-copilot.md @@ -934,7 +934,7 @@ Copilot on GitHub.com has context about your repositories, issues, PRs, and code ### What you can ask Copilot on GitHub.com -``` +```text # Ask about a specific repository "Summarize the recent changes to the accessibility-agents repo" diff --git a/docs/17-issue-templates.md b/docs/17-issue-templates.md index bb6abe73..dc1d1070 100644 --- a/docs/17-issue-templates.md +++ b/docs/17-issue-templates.md @@ -2127,7 +2127,7 @@ After completing Steps 1-7, verify: 1. Create a table: - ``` + ```text Field Name -- Type (dropdown/input/textarea) -- Why Required? -- Options (if dropdown) [name] -- [type] -- [reason] -- [choices] ``` diff --git a/docs/19-accessibility-agents.md b/docs/19-accessibility-agents.md index ba9fd00a..4273642f 100644 --- a/docs/19-accessibility-agents.md +++ b/docs/19-accessibility-agents.md @@ -873,7 +873,7 @@ All agents work the same across platforms, but the workflow differs slightly. **GitHub Copilot (VS Code):** -``` +```text Ctrl+Alt+I → Type: @aria-specialist audit this component for ARIA ``` @@ -891,7 +891,7 @@ gemini @aria-specialist audit this component for ARIA **Claude Desktop:** -``` +```text Open chat → Type: @aria-specialist audit this component for ARIA ``` diff --git a/docs/appendix-aa-agent-installation-setup.md b/docs/appendix-aa-agent-installation-setup.md index 1adf6e28..39c3e16a 100644 --- a/docs/appendix-aa-agent-installation-setup.md +++ b/docs/appendix-aa-agent-installation-setup.md @@ -117,7 +117,7 @@ git --version Expected output: -``` +```text 1.113.0 or higher (VS Code) github.copilot v18.0.0 or higher (Node.js) @@ -360,7 +360,7 @@ After installation, verify each platform is ready: **On GitHub Copilot (VS Code):** -``` +```text Open Chat (Ctrl+Alt+I) → Type: @daily-briefing morning briefing ``` diff --git a/docs/appendix-ab-advanced-agent-patterns.md b/docs/appendix-ab-advanced-agent-patterns.md index 8d5a8fa0..d2aee2c9 100644 --- a/docs/appendix-ab-advanced-agent-patterns.md +++ b/docs/appendix-ab-advanced-agent-patterns.md @@ -25,7 +25,7 @@ An **agent** is a standalone AI system (like `@aria-specialist`) that understand **Example workflow:** -``` +```text User: @web-accessibility-wizard [audit this page] ↓ (orchestrates multiple specialists) ├─→ @aria-specialist (check ARIA roles) @@ -120,7 +120,7 @@ Accessibility Agents includes a library of reusable skills organized by capabili **From Copilot Chat:** -``` +```text /web-scanning [URL] /report-generation [findings JSON] /python-fact-grounded-coding my_script.py @@ -435,7 +435,7 @@ await browser.close(); **Goal:** Audit multiple aspects of a page simultaneously for speed. -``` +```text User request: Audit this page │ ├─ @aria-specialist (scan ARIA) @@ -470,7 +470,7 @@ Invoke all specialist agents in parallel: **Goal:** Fix issues in order of severity and dependency. -``` +```text Findings identified: 1. Missing alt text (3 images) 2. Poor color contrast (5 elements) @@ -490,7 +490,7 @@ Output: Numbered PR suggestions, 1 fix per commit message **Goal:** Guide users through testing workflows without assuming prior knowledge. -``` +```text User: How do I test keyboard navigation? Agent (@testing-coach) response: @@ -516,7 +516,7 @@ Agent (@testing-coach) response: **Goal:** Consolidate findings across multiple pages into systemic issues. -``` +```text Input: 50 pages audited Output: @@ -591,7 +591,7 @@ Set up automated evaluation to measure improvement over time: Create platform-specific implementations of the same skill: -``` +```text .github/skills/form-accessibility/ ├── SKILL.md (base description) ├── implementations/ diff --git a/docs/appendix-ac-document-developer-tools.md b/docs/appendix-ac-document-developer-tools.md index a04fe2a1..5c5929ca 100644 --- a/docs/appendix-ac-document-developer-tools.md +++ b/docs/appendix-ac-document-developer-tools.md @@ -60,7 +60,7 @@ The Document Accessibility Team provides specialized agents for scanning, remedi **Using `@word-accessibility`:** -``` +```text User: @word-accessibility audit my-report.docx Agent response: @@ -76,7 +76,7 @@ Agent response: **Using `@office-remediator`:** -``` +```text User: @office-remediator fix-word my-report.docx Agent response: @@ -105,7 +105,7 @@ Agent response: **Using `@excel-accessibility`:** -``` +```text User: @excel-accessibility audit sales-data.xlsx Agent response: @@ -123,7 +123,7 @@ Agent response: **Using `@office-remediator`:** -``` +```text User: @office-remediator fix-excel sales-data.xlsx Agent response: @@ -151,7 +151,7 @@ Agent response: **Using `@powerpoint-accessibility`:** -``` +```text User: @powerpoint-accessibility audit presentation.pptx Agent response: @@ -170,7 +170,7 @@ Agent response: **Using `@office-remediator`:** -``` +```text User: @office-remediator fix-powerpoint presentation.pptx --add-speaker-notes Agent response: @@ -203,7 +203,7 @@ PDF/UA (Universal Accessibility) is the ISO standard for accessible PDFs. **Using `@pdf-accessibility`:** -``` +```text User: @pdf-accessibility audit report.pdf Agent response: @@ -219,7 +219,7 @@ Agent response: **Using `@pdf-remediator`:** -``` +```text User: @pdf-remediator fix-pdf report.pdf --ocr --add-bookmarks Agent response: @@ -248,7 +248,7 @@ EPUB files are digital publications (e-books, online articles). Accessibility re **Using `@epub-accessibility`:** -``` +```text User: @epub-accessibility audit ebook.epub Agent response: @@ -295,7 +295,7 @@ The Developer Tools Team supports accessible application development across Pyth **Using `@python-specialist`:** -``` +```text User: @python-specialist review my accessibility scanning script Agent response: @@ -329,7 +329,7 @@ wxPython is a cross-platform GUI toolkit. Accessibility requires following platf **Using `@wxpython-specialist`:** -``` +```text User: @wxpython-specialist audit my-app.py Agent response: @@ -402,7 +402,7 @@ Desktop applications must follow OS conventions: **Using `@desktop-a11y-specialist`:** -``` +```text User: @desktop-a11y-specialist test my-app --platform windows Agent response: @@ -426,7 +426,7 @@ NVDA (free, open-source screen reader) supports add-ons for extended functionali **NVDA add-on structure:** -``` +```text my-addon/ ├── addon/ │ ├── globalPlugins/ @@ -441,7 +441,7 @@ my-addon/ **Using `@nvda-addon-developer`:** -``` +```text User: @nvda-addon-developer create an add-on that improves announcement of custom web components Agent response: @@ -519,7 +519,7 @@ jobs: **Using `@ci-accessibility`:** -``` +```text User: @ci-accessibility add-workflow my-repo Agent response: @@ -567,7 +567,7 @@ test('form accessible by keyboard only', async ({ page }) => { **Using `@playwright-scanner`:** -``` +```text User: @playwright-scanner run tests/keyboard.spec.ts Agent response: diff --git a/docs/appendix-e-advanced-git.md b/docs/appendix-e-advanced-git.md index a5c474cd..e4be9d10 100644 --- a/docs/appendix-e-advanced-git.md +++ b/docs/appendix-e-advanced-git.md @@ -284,7 +284,7 @@ This is equivalent to `git reset --soft HEAD~1` — your changes come back as st #### Using the Command Palette -``` +```text Ctrl+Shift+P → type "git undo" → select "Git: Undo Last Commit" ``` @@ -396,7 +396,7 @@ git revert -m 1 a1b2c3d #### VS Code (Command Palette) -``` +```text Ctrl+Shift+P → type "git tag" → select "Git: Create Tag" ``` @@ -532,7 +532,7 @@ To return to a branch: Click that status bar area, or use `Ctrl+Shift+P` → **" VS Code doesn't have a "force push" button in the UI — this is intentional to prevent accidents. Use the integrated terminal: -``` +```text Ctrl+Backtick → then type the command below ``` @@ -875,7 +875,7 @@ Conventional commit format (`feat:`, `fix:`, `docs:`, `refactor:`) is especially Git's error messages and status output can be cryptic. Paste them directly into Copilot Chat: -``` +```text # Paste this kind of thing into Copilot and ask "what does this mean?" error: Your local changes to the following files would be overwritten by merge: src/auth/login.js @@ -905,7 +905,7 @@ When `git bisect` lands on a commit and you're not sure what to test: Paste the full error message from a rejected push into Copilot: -``` +```text remote: error: GH006: Protected branch update failed for refs/heads/main. remote: error: Required status check "CI / build" is failing. ``` diff --git a/docs/appendix-f-git-security.md b/docs/appendix-f-git-security.md index 2fac5762..fdb08faa 100644 --- a/docs/appendix-f-git-security.md +++ b/docs/appendix-f-git-security.md @@ -459,7 +459,7 @@ After removing the secret from history, go to **Security → Secret scanning** i ### Quick decision flowchart -``` +```text Secret committed │ ├─ Still local only (not pushed)? diff --git a/docs/appendix-h-github-desktop.md b/docs/appendix-h-github-desktop.md index bcb2c5d1..ad13d79a 100644 --- a/docs/appendix-h-github-desktop.md +++ b/docs/appendix-h-github-desktop.md @@ -150,7 +150,7 @@ That's it. GitHub Desktop stores your credentials securely in the system keychai GitHub Desktop has three main areas: -``` +```text ┌─────────────────────────────────────────────────────────┐ │ Toolbar: Current Repository ▾ | Current Branch ▾ | │ │ Fetch/Push button │ diff --git a/docs/appendix-k-copilot-reference.md b/docs/appendix-k-copilot-reference.md index aa1129bc..e3b7ea14 100644 --- a/docs/appendix-k-copilot-reference.md +++ b/docs/appendix-k-copilot-reference.md @@ -1821,7 +1821,7 @@ On GitHub.com, you can assign tasks to different AI agents, including third-part 4. Select the agent 5. Add a comment describing the task: - ``` + ```text @copilot please implement this feature and open a PR. ``` diff --git a/docs/appendix-l-agents-reference.md b/docs/appendix-l-agents-reference.md index d8ff4f9c..7c819c39 100644 --- a/docs/appendix-l-agents-reference.md +++ b/docs/appendix-l-agents-reference.md @@ -1453,7 +1453,7 @@ GitHub supports assigning cloud agents to issues and pull requests. You can use **GitHub cloud agent assignment syntax:** -``` +```markdown @copilot please implement this feature with accessibility best practices in mind. Reference: [Appendix K: GitHub Agentic Workflows](appendix-k-copilot-reference.md#14-github-agentic-workflows-and-third-party-agents) ``` diff --git a/docs/appendix-t-community-and-social.md b/docs/appendix-t-community-and-social.md index fd60ed81..fa12cfff 100644 --- a/docs/appendix-t-community-and-social.md +++ b/docs/appendix-t-community-and-social.md @@ -749,7 +749,7 @@ Every repository can be tagged with **topics** — keywords like `accessibility` Click any topic tag on a repository page to see all repos tagged with that topic. Or go directly: -``` +```text https://github.com/topics/accessibility https://github.com/topics/screen-reader https://github.com/topics/good-first-issue diff --git a/docs/solutions/solution-04-branch-out.md b/docs/solutions/solution-04-branch-out.md index 55b0cc30..74cbeaf5 100644 --- a/docs/solutions/solution-04-branch-out.md +++ b/docs/solutions/solution-04-branch-out.md @@ -13,7 +13,7 @@ The branch now exists on GitHub and is active. You can switch to it using the sa ## In VS Code (with Git) -``` +```bash git checkout -b fix/welcome-todo ``` @@ -28,7 +28,7 @@ Or use the Source Control sidebar: click the branch name in the bottom-left stat ## With GitHub CLI -``` +```bash gh repo clone /learning-room- cd learning-room git checkout -b fix/welcome-todo diff --git a/docs/solutions/solution-05-make-your-mark.md b/docs/solutions/solution-05-make-your-mark.md index d719f987..97063136 100644 --- a/docs/solutions/solution-05-make-your-mark.md +++ b/docs/solutions/solution-05-make-your-mark.md @@ -20,7 +20,7 @@ See the [workshop schedule](https://github.com/Community-Access/git-going-with-g ## Example commit message -``` +```text docs: replace TODO with workshop schedule link Resolves the placeholder on line 15 of welcome.md by adding @@ -35,11 +35,11 @@ a link to the schedule file. ### Simpler alternatives that are also fine -``` +```text Fix TODO in welcome.md ``` -``` +```text Add schedule link to welcome page ``` diff --git a/docs/solutions/solution-07-merge-conflict.md b/docs/solutions/solution-07-merge-conflict.md index d36db7f0..b42779ef 100644 --- a/docs/solutions/solution-07-merge-conflict.md +++ b/docs/solutions/solution-07-merge-conflict.md @@ -6,7 +6,7 @@ This shows what conflict markers look like and how to resolve them. When Git cannot automatically merge two changes to the same lines, it inserts markers: -``` +```text <<<<<<< HEAD Welcome to the Learning Room! This is the main branch version. ======= @@ -24,7 +24,7 @@ Welcome to the Learning Room! This is my improved version with more detail. **Before (with conflict markers):** -``` +```text <<<<<<< HEAD Welcome to the Learning Room! This is the main branch version. ======= @@ -34,7 +34,7 @@ Welcome to the Learning Room! This is my improved version with more detail. **After (resolved):** -``` +```text Welcome to the Learning Room! This is my improved version with more detail. ``` diff --git a/html/ACCESSIBILITY.html b/html/ACCESSIBILITY.html index 806a8139..7f141c96 100644 --- a/html/ACCESSIBILITY.html +++ b/html/ACCESSIBILITY.html @@ -62,7 +62,6 @@ name="q" placeholder="Search docs…" autocomplete="off" - aria-label="Search documentation" >