Requesting info/experiences: software engineering and web documentation for the blind/low-vision
I'm a technical writer. My company sells DevOps software mostly operated on the command line. I'm responsible for explaining this software via HTML5 documentation on our website.
One of our largest customers employs at least one software developer who is "totally blind" and requires a screen reader to work. I assume others exist, but they have not contacted us. Unfortunately, our website is not 100% ADA-compliant. It's far from the worst I've seen, but it could be a lot better.
I'm familiar with high-level web accessibility paradigms and am currently doing an informal audit of our website to determine what we need to improve to make it fully ADA-compliant. I've prioritized discovery for accessibility concerns in our next sprint. Eventually, I'd like to look into hiring a consultant to do a more robust analysis, but only if necessary because I'd need to request funding. Unfortunately, I have limited control over the text that displays in our product, just the documentation. Long-term, I'd like to collaborate with the product team to ensure our CLI is fully ADA-compliant.
I've begun reading web accessibility materials from the government. In the meantime, I wanted to ask: are any of you blind or low-vision, or have you used screen readers in the past? Or do you know any blind/low-vision devs? Either way, can you provide any personal insight into any of the things I can do as a technical writer to improve the usability of software documentation for the purpose of enabling you to do your job? My goal is to make the documentation experience great for screen reader users, not just OK.
I recently discovered cloudinary‘s AI powered alt-text generator. Obviously one needs to proofread, but the results were pretty good and generally usable.
So here's a free consultation, for what it's worth... My spouse regularly works on big content management systems that have ADA-compliance requirements.
His advice: He confirms that /u/Gunbudder's advice is good, particularly with respect to adding alt text wherever applicable.
Also, run a WAVE report on your documentation pages. Address any H1, H2, etc. level problems found, then run the report again. Chances are that once you've resolved tag structure and image tagging issues, the exceptions will be down to a limited number of edge cases.
If you need automation, look at https://docs.deque.com/devtools-html/4.0.0/en/cli-home
ADA-compliant CLI is a very interesting idea. It looks like a few people at Google did a small paper: https://dl.acm.org/doi/fullHtml/10.1145/3411764.3445544
edit: One thing that I do in my CLIs is output all tables as GitHub style markdown tables. This might be an easy lift for your product. I don't know that this will solve any grievances for low-vision people but at least it makes it easier for all people to copy and paste tables into a spreadsheet. I'm sure it would be a step up from an arbitrarily formatted ASCII table
Take a look at Cursorless, a spoken word programming language.
Cursorless
Unfortunately I am unable to get videos on my phone right now, but you can search for his talk at Strange Loop 2023 to see how it works.
https://thestrangeloop.com/2023/cursorless-a-spoken-language-for-editing-code.html
Make sure to do some light reading (or hardcore, if you want) into the 'a11y' space for some tips and tricks. Accessibility is a nightmare to write, so a11y works.
There's a decent checklist found over at the A11y Project