From d9e556820eec6e624b8756cff02458f22ccfdd2c Mon Sep 17 00:00:00 2001 From: Isabela Presedo-Floyd Date: Mon, 3 Mar 2025 16:15:56 -0800 Subject: [PATCH 1/3] Add Accessible Documentation guide in Documentation section --- documentation/_index.md | 18 +++ documentation/accessible-documentation.md | 188 ++++++++++++++++++++++ 2 files changed, 206 insertions(+) create mode 100644 documentation/_index.md create mode 100644 documentation/accessible-documentation.md diff --git a/documentation/_index.md b/documentation/_index.md new file mode 100644 index 0000000..e461325 --- /dev/null +++ b/documentation/_index.md @@ -0,0 +1,18 @@ +--- +title: "Documentation Guide" +shortcutDepth: 2 +--- + +Welcome to the Documentation Guide! Here you will find resources that describe documenting practices relevant to the ecosystem. + +## Documentation Authoring + +{{< grid columns="1 2 2 3" >}} + +[[item]] +type = 'card' +title = 'Accessible Documentation' +link = 'accessible-documentation' +body = 'Learn about how to structure and write project documentation that considers disabled and abled readers.' + +{{< /grid >}} diff --git a/documentation/accessible-documentation.md b/documentation/accessible-documentation.md new file mode 100644 index 0000000..d0a753f --- /dev/null +++ b/documentation/accessible-documentation.md @@ -0,0 +1,188 @@ +--- +title: "Accessible Documentation" +--- + +## Covered in this guide + +- What accessible documentation means +- What work documentation authors have control over and responsibility for +- Recommendations for accessible documentation structure, text, images, and videos +- What areas documentation authors can advocate for or select for accessibility in others' work +- A checklist for quick documentation accessibility review +- External resources related to these topics + +## Sources + +This guide was written based on + +- The [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/TR/WCAG22/) principles +- [Accessibility user research with Space Telescope Science Institute](https://github.com/Iota-School/notebooks-for-all/tree/main/user-tests#test-1-navigation) and [Project Jupyter](https://github.com/jupyter/surveys/tree/master/surveys/2023-05-jupyterlab-accessibility#readme) +- Documentation workshops in the Scientific Python project ecosystem +- Experience doing accessibility work on open source projects. + +It was written by Isabela Presedo-Floyd at Quansight Labs. + +## What is accessible documentation? + +If you've made it to this guide in the first place, [accessibility](https://en.wikipedia.org/wiki/Web_accessibility) may be familiar to you already. Ultimately, the goal is to build an equitable world for disabled and able people; for documentation, this starts by making sure that disabled people can benefit from your documentation the same ways that abled people can whether they are blind or visually impaired, have limited mobility, are deaf or hard of hearing, or have mental disabilities. + +This is a wide net to cast. Not only is there a breadth of experience and acommodations needed for all disabilities, the things that help one disabled person are often the exact things that would be impossible to use for another. So how in the world is accessible documentation even possible? + +When in doubt: +- **Write it out.** Text is one of the most flexible and adaptable methods of communication digitally. It can be read visually, audibly, haptically, and be translated to other forms with the right technology. (Note, this does not apply to images of text.) +- **Provide multiple options.** Instead of having *only* text or *only* images to explain a concept, have both. This allows people to engage as they need, it provides multiple paths instead of a single path that can become a wall depending on someone's ability. +- **Use things as they are intended.** For example, if you are writing documentation in plain HTML, use HTML elements as they are intended (often called [semantic HTML](https://developer.mozilla.org/en-US/curriculum/core/semantic-html/)); use `