Screen reader text obscures search about ex_doc

[angelikatyborska]

Thanks for tagging me! This is an interesting problem that I haven't thought about before 😁

There isn't a way to hide text content from the browser's search functionality without also hiding it from screen readers, but there is a way to provide accessible names to interactive elements without putting them as text content on the page.

The aria-label attribute can be used on interactive elements. So instead of:

<a href="#c:available?/0" class="detail-link" data-no-tooltip="" title="Link to this callback">
  <i class="ri-link-m" aria-hidden="true"></i>
  <span class="sr-only">Link to this callback</span>
</a>

those links could look like this:

<a href="#c:available?/0" class="detail-link" data-no-tooltip="" title="Link to this callback"  aria-label="Link to this callback">
  <i class="ri-link-m" aria-hidden="true"></i>
</a>

A few notes:

• both title and aria-label are necessary because VoiceOver does not announce a link's title when reading a page
• content of aria-label is usually ignored by addons that translate pages to different natural languages whereas text content in sr-only elements is translated, which is one reason to favor usages of sr-only
• aria-label can only be added to interactive elements like links, buttons, inputs, selects

Given the type of project this is (code documentation, long text), it'd say it's worth improving the browser search experience by switching to aria-labels where possible. Searching through long text is a common use-case whereas autotranslating a page that has both natural language and programming language on it doesn't produce the best results anyway, so I don't expect a lot of users to rely on autotranslating.

[angelikatyborska]

I checked out v0.22.4 and ran it locally to check up on #1272

The cause of that bug is this line of code: https://github.com/elixir-lang/ex_doc/pull/1265/files#diff-ede8dc6a8e76652ad86e8ac0a1a884efadb2e56ccf56d40a1f339d0eebcd2612R107-R108

It's a different PR from the same user around the same time, but unrelated to aria-label. There should be no CSS side-effects of replacing sr-only elements with aria-label.

As an aside, the available information on this is pretty frustrating. There's a fair amount of contradicting recommendations and best practices.

Well, what can I tell you? HTML is written by so many different people with different levels of expertise in it, and nobody verifies your experience when you leave a StackOverflow answer, so the internet is full of partially misleading advice 🤷 and as with many topics in software, there are often no "best solutions", just trade-offs.

The information I gave you in my previous response is based on the book Web Accessibility Cookbook by Manuel Matuzovic (a web accessibility specialist), who in turn was inspired by this blogpost by another web accessibility specialist: My Priority of Methods for Labeling a Control (note: a visually-hidden CSS class is the same concept as sr-only).

[josevalim]

I believe those are indeed needed but maybe we can rule them out from search. Let's ping @angelikatyborska, who did most contributions around screen reader. She may have good insights around this. ❤️

[josevalim]

Thanks @angelikatyborska! @harrisi, would you like to send a PR that moves links and buttons to aria-label?

[harrisi]

Definitely, I'll see if I have time later today.

[harrisi]

I found a previous PR that added aria-label: #1266. I'm not sure why it was reverted, but it looks somewhat similar to what I'd like to add. Before I open a PR doing the same work, is there anything I should know about why #1266 was reverted?

As an aside, the available information on this is pretty frustrating. There's a fair amount of contradicting recommendations and best practices. It still seems like aria-label is ideal, but if anyone has more actual user experience, that could help.

[josevalim]

Unfortunately I don't remember why :( and it seems we did not attach any information. My guess was that it had visual defects on the page.

[josevalim]

This is most likely the root cause: #1272

The revert happens immediately after the release of 0.22.4, and it only reverts both of these commits:

commit a939465b64a615c55f16ca05594da04aaa6cd5f7 (tag: v0.22.5)
Author: José Valim <[email protected]>
Date:   Sun Sep 13 12:46:50 2020 +0200

    Release v0.22.5

commit 6bfc91666540bfee19c56ad3eef2a7e81a7092a4
Author: José Valim <[email protected]>
Date:   Sun Sep 13 12:44:55 2020 +0200

    Revert "Accessibility: Restructure headings (#1265)"

    This reverts commit 823210352ab0bfdec4e9a8e59f759f95dda65db0.

commit 8d64cd7151c5e1015a8687eb6b596606ffbb32ec
Author: José Valim <[email protected]>
Date:   Sun Sep 13 12:44:49 2020 +0200

    Revert "Add aria-label and title attributes to links (#1266)"

    This reverts commit 848a501e2d625fc1539ff30088f004f9dc6f7f7f.

commit 3614e8a5e2fae151b1a2720a6f7de059fa1d2dde (tag: v0.22.4)
Author: José Valim <[email protected]>
Date:   Sat Sep 12 15:18:19 2020 +0200

    Release v0.22.4

[harrisi]

Okay, that helps. I'll make sure to check for that, thanks!

[halostatue]

@angelikatyborska Thank you for pointing out that book and the blog post, which I think will be very useful for future accessibility work that I do.