Merge pull request #168 from Community-Access/wicky

Wiki-ready docs: SVG diagrams, prose descriptions, accessible formatting

Author: taylorarndt

.github/workflows/generate-diagram-svgs.yml

@@ -0,0 +1,41 @@
+name: Generate Diagram SVGs
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'scripts/generate-diagram-svgs.py'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Generate SVGs
+        run: python scripts/generate-diagram-svgs.py
+
+      - name: Commit and push SVGs
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add docs/images/*.svg
+          if [ -n "$(git status --porcelain)" ]; then
+            git commit -m "chore: regenerate diagram SVGs from script"
+            git push
+          else
+            echo "No SVG changes to commit"
+          fi

docs/01-understanding-github-web-structure.md

@@ -68,11 +68,7 @@ Visually, the top bar contains (left to right):
 
 ### Secondary navigation (repository pages only)
 
-When you are inside a repository, a second navigation bar appears below the global bar. This contains the repository's tabs:
-
-```text
-Code | Issues | Pull requests | Actions | Projects | Wiki | Security | Insights | Settings
-```
+When you are inside a repository, a second navigation bar appears below the global bar. This contains the repository's tabs: Code, Issues, Pull requests, Actions, Projects, Wiki, Security, Insights, and Settings.
 
 **Screen reader landmark:** This is labeled **"Repository navigation"**. Press `D` to jump to it directly.
 
@@ -198,43 +194,15 @@ Your personal home (`github.com`) shows activity from repositories you follow. Y
 
 ## 5. Visual Map of a Repository Page
 
-This diagram shows the layout of a repository home page. It is presented as ASCII art - every screen reader will read it correctly as text, left to right, top to bottom.
+![](images/repo-page-layout-01.svg)
 
-```text
-+----------------------------------------------------------+
-|  GLOBAL NAVIGATION (landmark: "Navigation Menu")         |
-|  [GitHub] [Search] [Copilot] [PRs] [Issues] [Bell] [You]|
-+----------------------------------------------------------+
-|  REPOSITORY TABS (landmark: "Repository navigation")     |
-|  [Code] [Issues 12] [Pull requests 3] [Actions] [...]   |
-+----------------------------------------------------------+
-|  REPOSITORY HEADER                                        |
-|  owner / repo-name  (this is the H1 heading)             |
-|  [Star 42]  [Watch]  [Fork 8]                             |
-+-----------------------------+----------------------------+
-|  FILE AREA                  |  SIDEBAR                   |
-|  Branch: [main v]           |  About                     |
-|  [Go to file]  [Code v]     |  Description text          |
-|                             |  Topics: accessibility     |
-|  FILE TABLE (landmark)      |  Releases: 3               |
-|  .github/     3 days ago    |  Contributors: 5           |
-|  docs/        2 days ago    |  Languages: Markdown 100%  |
-|  README.md    yesterday     |                            |
-+-----------------------------+----------------------------+
-|  README (landmark: "Repository files navigation")         |
-|  # Rendered README content here                           |
-|  ...                                                      |
-+----------------------------------------------------------+
-|  FOOTER                                                   |
-+----------------------------------------------------------+
-```
+### Description
+
+A repository home page is laid out from top to bottom as follows. The Global Navigation bar (landmark: "Navigation Menu") contains the GitHub logo, Search, Copilot, Pull Requests, Issues, Notifications bell, and your avatar. Below that are the Repository Tabs (landmark: "Repository navigation") showing Code, Issues (12), Pull requests (3), Actions, and more. Next is the Repository Header, which is the H1 heading "owner / repo-name" plus Star (42), Watch, and Fork (8) buttons. The main content area is split into two columns. On the left is the File Area with the branch selector (main), Go to file button, Code button, and the File Table (a landmark) listing files like .github/, docs/, and README.md with dates. On the right is the Sidebar with the About section, description text, topics (accessibility), Releases (3), Contributors (5), and Languages (Markdown 100%). Below both columns is the rendered README (landmark: "Repository files navigation"), and at the bottom is the Footer.
 
 ### Screen reader navigation of this page
 
-- `1` → hear "owner/repo-name" (the H1, confirms you are on the right repo)
-- `D` → "Navigation Menu" → `D` → "Repository navigation" → `D` → "Main" (file tree area)
-- `T` → jump to the file table → `Ctrl+Alt+Down Arrow` to navigate rows
-- `D` → "Repository files navigation" → read the README
+Press 1 to hear "owner/repo-name" (the H1, confirms you are on the right repo). Press D to hear "Navigation Menu," then D again for "Repository navigation," then D again for "Main" (the file tree area). Press T to jump to the file table, then Ctrl+Alt+Down Arrow to navigate rows. Press D again to reach "Repository files navigation" and read the README.
 
 
 ## 6. Screen Reader Orientation Sequence

docs/02-navigating-repositories.md

@@ -29,27 +29,11 @@ Use this sequence before moving to graded chapters:
 
 When you navigate to a GitHub repository (e.g., `https://github.com/owner/repo-name`), you land on the **repository home page** (also called the Code tab). This page has several distinct regions:
 
-```text
-┌────────────────────────────────────────────────────┐
-│  Navigation bar (GitHub global nav)                │
-│  avatar menu | Notifications | search               │
-├────────────────────────────────────────────────────┤
-│  Repository header                                  │
-│  owner / repo-name  (h1)                            │
-│  [Star] [Watch] [Fork] buttons                      │
-├────────────────────────────────────────────────────┤
-│  Repository navigation tabs (landmark)              │
-│  < Code > Issues  Pull requests  Actions  etc.      │
-├─────────────────────────────┬──────────────────────┤
-│  File tree / code panel     │  Sidebar              │
-│  Branch selector            │  About section        │
-│  Files table (t:table)      │  Topics               │
-│  Last commit message         │  Releases             │
-├─────────────────────────────┴──────────────────────┤
-│  README.md (rendered)                               │
-│  (a separate landmark region)                       │
-└────────────────────────────────────────────────────┘
-```
+![](images/repo-page-layout-02.svg)
+
+### Description
+
+The repository home page is organized from top to bottom as follows. The Navigation bar (GitHub global nav) contains the avatar menu, Notifications, and search. Below that is the Repository header showing "owner / repo-name" as the H1 heading, plus Star, Watch, and Fork buttons. Next are the Repository navigation tabs (a landmark) with Code (active), Issues, Pull requests, Actions, and more. The main content area is split into two columns: on the left is the File tree / code panel with the branch selector, Files table (navigable as a table), and last commit message; on the right is the Sidebar with the About section, topics, and releases. Below both columns is the rendered README.md in a separate landmark region.
 
 
 ## Landing on a Repository - What to Expect

docs/03-the-learning-room.md

@@ -23,15 +23,11 @@ Before starting Chapter 4 challenges, students should be able to:
 2. Explain issue -> branch -> PR -> review -> merge.
 3. Identify where bot feedback appears on PRs.
 
-```text
-learning-room (SHARED)
-├── main branch (protected)
-├── Student A's PR #12 (open, assigned to Student B for review)
-├── Student B's PR #13 (open, assigned to Student C for review)
-├── Student C's PR #14 (open, assigned to Student A for review)
-├── Student A's PR #11 (merged, closed)
-└── [More PRs as students contribute]
-```
+![](images/learning-room-tree.svg)
+
+#### Description
+
+The learning-room is a single shared repository. It has a protected main branch, and each student opens pull requests against it. For example: Student A's PR #12 is open and assigned to Student B for review, Student B's PR #13 is assigned to Student C, Student C's PR #14 is assigned to Student A, and Student A's earlier PR #11 has already been merged. More PRs appear as students contribute.
 
 ### Why one shared repo?
 
@@ -68,48 +64,41 @@ Throughout Day 1, you work on **two parallel learning tracks**:
 
 #### The Two Tracks Reinforce Each Other
 
-```text
-Skills Module (individual)      Learning Room (group)
-     ↓                               ↓
-Create a branch                 Create a branch (together)
-     ↓                               ↓
-Open a PR                       Open a PR (see others' too)
-     ↓                               ↓
-Get instant bot feedback        Get bot feedback + human review
-     ↓                               ↓
-Mona verifies your step         Human peer reviewer approves
-     ↓                               ↓
-Next step unlocked             Ready to merge
-```
+| Step | Skills Module (individual) | Learning Room (group) |
+| --- | --- | --- |
+| 1 | Create a branch | Create a branch (together) |
+| 2 | Open a PR | Open a PR (see others' too) |
+| 3 | Get instant bot feedback | Get bot feedback + human review |
+| 4 | Mona verifies your step | Human peer reviewer approves |
+| 5 | Next step unlocked | Ready to merge |
 
 
 ## Learning Room Folder Structure
 
-```text
-learning-room/
-├── README.md                           ← Getting started guide
-├── AUTOMATION.md                       ← How the bot works
-├── .github/
-│   ├── workflows/                      ← 3 automation workflows
-│   │   ├── learning-room-pr-bot.yml            (PR validation)
-│   │   ├── skills-progression.yml              (progress tracking)
-│   │   └── student-grouping.yml                (peer pairing)
-│   ├── scripts/
-│   │   └── validate-pr.js                      (validation logic)
-│   ├── data/
-│   │   ├── student-roster.json                 (your cohort info)
-│   │   └── challenge-progression.json          (levels, badges)
-│   └── docs/
-│       ├── LEARNING_PATHS.md                   (skill progression guide)
-│       └── IMPLEMENTATION_GUIDE.md             (facilitator setup)
-├── docs/
-│   ├── CHALLENGES.md                   ← 12 challenges (Beginner → Expert)
-│   ├── GROUP_CHALLENGES.md             ← 7 collaborative exercises
-│   ├── welcome.md                      ← Has [TODO] to complete
-│   ├── keyboard-shortcuts.md           ← Has intentional errors
-│   └── setup-guide.md                  ← Has broken links
-└── [other files for practice]
-```
+The learning-room repository contains these files and folders:
+
+- **README.md** -- Getting started guide
+- **AUTOMATION.md** -- How the bot works
+- **.github/**
+  - **workflows/** -- 3 automation workflows
+    - learning-room-pr-bot.yml (PR validation)
+    - skills-progression.yml (progress tracking)
+    - student-grouping.yml (peer pairing)
+  - **scripts/**
+    - validate-pr.js (validation logic)
+  - **data/**
+    - student-roster.json (your cohort info)
+    - challenge-progression.json (levels, badges)
+  - **docs/**
+    - LEARNING_PATHS.md (skill progression guide)
+    - IMPLEMENTATION_GUIDE.md (facilitator setup)
+- **docs/**
+  - CHALLENGES.md -- 12 challenges (Beginner to Expert)
+  - GROUP_CHALLENGES.md -- 7 collaborative exercises
+  - welcome.md -- Has a TODO to complete
+  - keyboard-shortcuts.md -- Has intentional errors
+  - setup-guide.md -- Has broken links
+- Other files for practice
 
 
 ## Your Practice Branch

docs/04-working-with-issues.md

@@ -251,11 +251,11 @@ 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
-[Pagination]                   ← at the bottom
+```
+[Search / filter bar]          -- controls at the top
+[State tabs: Open / Closed]    -- filter by status
+[Issues list]                  -- each issue is one list item or heading
+[Pagination]                   -- at the bottom
 ```
 
 ### How to read the issue list

docs/06-merge-conflicts.md

@@ -290,13 +290,13 @@ 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 |
+  Insert+Space -- Toggle between Browse Mode and Focus Mode
+  Insert+F5 -- List elements by type
 =======
-| Insert+Space | Toggle between Browse Mode and Focus Mode |
-| Insert+F7 | Elements list (links, headings, form fields) |
+  Insert+Space -- Toggle between Browse Mode and Focus Mode
+  Insert+F7 -- Elements list (links, headings, form fields)
 >>>>>>> add-nvda-shortcut
 ```
 
@@ -383,10 +383,10 @@ 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)
+======= original                   -- (3-way merge, if enabled)
 Original version before both edits
 =======
 Incoming version

docs/12-github-pull-requests-extension.md

@@ -190,18 +190,11 @@ gh pr list --search "review-requested:@me"
 
 ### Pull Request Tree Structure
 
-```text
-GitHub Pull Requests
-├── My Pull Requests
-│   ├── Assigned to Me
-│   ├── Created by Me
-│   ├── Waiting for my Review
-│   └── All Open
-├── [Repository Name]
-│   ├── Local Pull Request Branches (checked out locally)
-│   ├── All Open Pull Requests
-│   └── All Closed Pull Requests
-```
+![](images/pr-tree.svg)
+
+#### Description
+
+The GitHub Pull Requests panel has two top-level sections. "My Pull Requests" contains four filters: Assigned to Me, Created by Me, Waiting for my Review, and All Open. The repository section shows Local Pull Request Branches (checked out locally), All Open Pull Requests, and All Closed Pull Requests.
 
 #### Screen reader announcement example
 

docs/14-accessible-code-review.md

@@ -242,32 +242,32 @@ Each file's diff is a table. Every row is one line of code.
 <details>
 <summary>Screen reader users - NVDA</summary>
 
-```text
-Press T to jump to the diff table → Insert+Space (Focus Mode)
-Press ↓ to move through lines one at a time
-Press Ctrl+Alt+→ to read across columns: [line number] | [change type] | [code content]
+```
+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
 ```
 
 </details>
 
 <details>
 <summary>Screen reader users - JAWS</summary>
 
-```text
-Press T to jump to the diff table → Insert+Z (Virtual PC Cursor off)
-Press ↓ to move through lines
-Press Ctrl+Alt+→ for column-by-column reading
+```
+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
 ```
 
 </details>
 
 <details>
 <summary>Screen reader users - VoiceOver (macOS)</summary>
 
-```text
-Press T or VO+U → Tables → select the diff table
-VO+Shift+↓ to enter the table
-VO+→/← to navigate columns, VO+↑/↓ to navigate rows
+```
+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
 ```
 
 </details>

docs/15-issue-templates.md

@@ -193,16 +193,11 @@ Without this context, maintainers ask follow-up questions - which delays the fix
 
 Templates live in a specific folder in your repository:
 
-```text
-your-repo/
-└── .github/
-    ├── ISSUE_TEMPLATE/
-    │   ├── bug_report.md         ← Markdown template
-    │   ├── feature_request.md    ← Markdown template
-    │   ├── accessibility-bug.yml ← YAML form template
-    │   └── config.yml            ← Template chooser configuration
-    └── pull_request_template.md  ← PR template (singular)
-```
+![](images/template-folder-tree.svg)
+
+### Description
+
+Templates live inside your-repo/.github/. The ISSUE_TEMPLATE/ subfolder contains: bug_report.md (Markdown template), feature_request.md (Markdown template), accessibility-bug.yml (YAML form template), and config.yml (template chooser configuration). The pull_request_template.md file sits directly in .github/, not inside ISSUE_TEMPLATE/.
 
 **Markdown templates (`.md`):** Traditional template format. Pre-fills a text editor with structured Markdown content. Contributors edit the template directly, replacing instructions and placeholder text with their own content.
 
@@ -1927,9 +1922,9 @@ 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]
+   ```
+   Field Name -- Type (dropdown/input/textarea) -- Why Required? -- Options (if dropdown)
+   [name]     -- [type]                        -- [reason]      -- [choices]
    ```
 
 2. For each issue type from Part 2, add 2-4 required fields: