Human-Centered Documentation for Web Developers | Hacker News Reader

Human-Centered Documentation for Web Developers

africakenyah.com

44 pointsmooreds12 comments

> screen readers

Let's say that as a non visually impaired developer I want to test one of my sites with a screen reader. In almost 30 years of work none of my customers asked me to do that, but anyway... I know about ARIA, I sometimes use those attributes in tags because they are in the Bootstrap examples but most of the times I don't. Customer requirements are about other things, again.

The obvious thing to do is probably buying a screen reader (software, hardware?) that works on my Ubuntu laptop. I got the feeling that this is a bad OS choice to start with.

Then the cost of the license or of the software. Then learning how to use it and actually using it, which must take more time than not using it.

Then iterating many times and learning how to design a site so that a screen reader can be used efficiently.

Is there anybody here who went through all of this and what was the outcome?

There's a handful of browser extensions to help with testing. In Chrome I've used Screen Reader from Google[1] and SilkTide[2] for testing accessibility issues.

[1] https://chrome.google.com/webstore/detail/screen-reader/kgej...

[2] https://chrome.google.com/webstore/detail/silktide-website-a...

Ubuntu has a built in screen reader, Orca [1].

"Welcome to Orca Orca is a free, open source, flexible, and extensible screen reader that provides access to the graphical desktop via speech and refreshable braille. Orca works with applications and toolkits that support the Assistive Technology Service Provider Interface (AT-SPI), which is the primary assistive technology infrastructure for Linux and Solaris. Applications and toolkits supporting the AT-SPI include the GNOME Gtk+ toolkit, the Java platform's Swing toolkit, LibreOffice, Gecko, and WebKitGtk. AT-SPI support for the KDE Qt toolkit is being pursued." [1] https://help.ubuntu.com/stable/ubuntu-help/a11y-screen-reade...

MacOs has VoiceOver built-in, which is free. The web is also quite accessible by default. I worked for the a11y branch of a big webapp, px fonts and such are not that big of a problem.

And Windows has Narrator built-in.

Also ChromeOS has a semi-decent screen reader built in too.

MacOs, Windows, and ChromeOS are devmcent. Linux as usual is a cluster fuck - it has basic functionality available, but it is lacking almost all features from what I can tell - e.g. skipping words/paragraphs, listing links/headings/forms/inputs/landmarks etc. I don't test on Linux as I figure that anyone who needs to use a screen reader won't be using Linux as the support seems to awfully backwards compared to other OSs

If you have access to an iOS device I've found this guide to testing in VoiceOver extremely useful: https://webaim.org/articles/voiceover/mobile

In many western countries it is a legal requirement to have an accessible site. Not just public ones either - internal-only sites still need to be accessible in many countries since internal users need to do their jobs too. Have your customers "asked" for the code to not be awful, or for there not to be security issues, or for it to be performant and so on? They're all kinda "implicit" non-functional requirements in my mind. We make the code non-shit and performant just as part of our job without anyone asking, and a11y is probably something we should do by default too.

It is very easy to make some absolute show-stopping errors with accessibility if you are not developing with it in mind, but luckily there is a lot of good free tooling that will catch 80-90% of the issues.

The Chrome Dev tools, OS-built-in screen readers, aXe for automated testing, and some very basic knowledge will get you a lot of the way (e.g. chrome dev tools accessibility tree view is awesome), but there will be some bits that require hands-on knowledge and engineering to implement/test/fix - e.g. making a table keyboard accessible is "trivial" from a technical perspective, but it might still be an awful experience for the users if you don't give it some care and thought (e.g. do you need to make every cell navigable via keyboard, or can you just do perhaps each row...? It really depends on your use case and that is where it gets harder of course!)

I'd recommend trying to use a screen reader from time to time. If you are used to seeing a page then it is a total culture-shock and feels totally impossible . However persevere and try to put your self I to the mindset of listening to a podcast/radio show or simply reading a fiction book etc and you'll slowly get the hang of it. Start slow and don't expect to be as fast as you are used to being when visually reading/scanning a page.

Some.of the fundamentals and errors I see so so so frequently:

- make sure the DOM is in a logical order (i.e. elements nested correctly and in a logical order - don't use CSS or JavaScript to move things around visually ... Elements should follow each other in the DOM logically)

- use HTML semantics properly - use <button> not <div class=button>, use <a> not <div onclick=navigate(foo)>, use <h1> not <div class=heading> etc etc etc. This is so common.

- use sensible labels

- check color contrast is sensible.

Just those few things will take you a long way to at least making your page comprehensible for assistive technology users, even if there are a few other rough edges elsewhere

Good luck.

> None of my customers have ever asked... Buy a license... Learn how to use a screen reader...

You might be overthinking it. Get a blind person/screen reader user to use your site to provide you feedback. It's the same as any usability study. Even if you did learn how to use a screen reader, you'd miss a lot of the nuance of using one. It's a lot of hot keys, jumping around the DOM, and switching between different input modes

Although the article 1) is a good reminder that perhaps more people than we think struggle to read documentation and 2) provides useful solutions, I do have some criticism.

As time goes on more often I see people complain about documentation to be 'too technical'. This typically comes from people who are self-taught or went to a boot camp. The author, a self-taught developer who started writing code seven months[0] before writing the article on better readability and usability of technical documentation, prompts to 'avoid jargon'.

Jargon makes documentation more readable and more usable. By definition it is a short description for something common in our field of work. Any non-jargon description would be more long-winded.

The author lists 'avoid jargon' as a method to make documentation more accessible. I opine avoiding jargon has nothing to do with accessibility, at most with inclusiveness. And indeed, right after mentioning avoiding jargon the author brings up 'use inclusive language', including 'avoid using gendered language'.

Whether or not inclusiveness in the way the author describes is important in technical documentation is a separate matter. Let us please not muddy the waters. You have all the rights to share your political opinions, but do not hide them among otherwise fairly objective suggestions to improve accessibility.

[0] https://www.africakenyah.com/learning-to-code-part-1/".

I write English documentation about German bureaucracy. I must use German terms because it’s what people will encounter in the wild. Using one specific term consistently affords us precision and unambiguity. It’s unavoidable.

I also can’t repeat the basics on every page. It would distract from the main topic of the page. I can’t teach you everything again on every page, for brevity’s sake.

I borrowed a solution from Wikipedia: popup word definitions. Click a word and get an explanation of what it is. You can keep reading if you know the concept, or click a word to know more.

I also borrowed “read more” links from the NHS. They link to a completely separate but related set of instructions. Wikipedia also does this when a subsection expands into its own entry.

Inclusiveness is achievable with a bit of design. Good documentation is as much about structure as it is about text.

I like the concept of a "coding therapist."

Documentation is pretty difficult. I take it seriously, but I'm not as good at it, as I would like.

Reply on news.ycombinator.com