## Summary Add user-facing documentation explaining how to navigate diffs with screen readers in GitLab, based on internal discussion and external feedback about accessibility of complex UIs like diffs for screen reader users. ### Problem The diff UI in GitLab is relatively complex, and it’s not obvious how to navigate it efficiently with a screen reader. We don’t currently have a dedicated doc/tutorial aimed at screen reader users that explains: - How diff views are structured semantically (files, hunks, comments). - Strategies for navigating diffs with common screen readers. - Important keyboard shortcuts and patterns. - Known limitations or workarounds. There is active external interest (e.g. a Mastodon thread) in guidance and tips for using GitLab more effectively with assistive tech, and we’d like to be able to share concrete documentation in response. ### Proposal - Create a new user doc page or tutorial focused on “Navigating diffs with screen readers”, likely under: - Existing accessibility documentation, and/or - Merge request / code review documentation sections. - The doc should cover at least: - How the diff view is organized (files, hunks, inline/side‑by‑side, comments). - Recommended navigation patterns for screen reader users (e.g. via headings, regions, landmarks, or other structural hooks). - Any relevant keyboard shortcuts that are especially useful with screen readers. - Known constraints and suggested strategies where the experience is more challenging. - Coordinate with Technical Writing and Accessibility: - Check for existing examples of docs written specifically with screen readers in mind and follow any existing patterns. - Confirm whether there is ongoing work around accessibility documentation and align this page with that broader effort. ## Out of scope Changes to the diff UI itself, including ARIA roles or markup changes. Any non-doc UX changes should be captured in follow-up issues if needed. ## Implementation plan - [ ] Confirm exact location and structure for the new page in the docs (TW + Accessibility/UX). - [ ] Draft the “Navigating diffs with screen readers” documentation. - Review with: - [ ] Technical Writing - [ ] At least one person with accessibility / screen reader expertise - [ ] Merge the doc update into `gitlab-org/gitlab`. - [ ] Share the link internally and, if agreed, in the referenced Mastodon thread. ## References 1. [Internal Slack thread in #f_rapid_diffs](https://gitlab.slack.com/archives/C05RW2HPY4C/p1772703015466189) 2. [External Mastodon discussion](https://mastodon.social/@funkylab/116122432422937813) referenced in the thread. 3. GitLab Team Member Social Media Policy (for external engagement context): https://handbook.gitlab.com/handbook/marketing/team-member-social-media-policy/