x/tools/cmd/godoc: improve accessibility #22171
Comments
|
Change https://golang.org/cl/69130 mentions this issue: |
|
Change https://golang.org/cl/69150 mentions this issue: |
The gopher with a miner hat on /pkg had no alt attribute so screen readers would announce the image by its filename. As the image is purely decorative, adding the empty string as alternative text prevents the image from being announced. For golang/go#22171 Change-Id: Ib214f296d3d9f9084c44d4e33d1cbe432f2183ed Reviewed-on: https://go-review.googlesource.com/69130 Reviewed-by: Ian Lance Taylor <iant@golang.org>
|
Change https://golang.org/cl/69190 mentions this issue: |
|
Change https://golang.org/cl/69210 mentions this issue: |
|
Change https://golang.org/cl/69171 mentions this issue: |
The heading of the #pkg-index section of package documentation pages uses an h2 heading but its 'Examples' and 'Package files' subsections use h4 headings, skipping the h3 level. This change switches the h4s to h3s and adds styling to preserve the current font-size with the new heading level. For golang/go#22171 Change-Id: Ifd2cacab22c1e82fd6f061b9322523fa5859a80f Reviewed-on: https://go-review.googlesource.com/69171 Reviewed-by: jimmy frasche <soapboxcicero@gmail.com> Reviewed-by: Andrew Bonventre <andybons@golang.org>
|
I created a wiki page for anyone who wants to help out or to make sure that tools they create are as accessible as possible: https://github.com/golang/go/wiki/WebAccessibilityResourcesAndTips |
This CL makes permalinks accessible to keyboard-users and screen readers. Adding an aria-label to permalinks overrides the default content of "pilcrow". As the permalinks only showed on hover they were inaccessible to users who could only use a keyboard and are now always shown. For golang/go#22171 Change-Id: I6ce3828dfedfd7edc29dd16f3eb94a0abcabfc7c Reviewed-on: https://go-review.googlesource.com/69210 Reviewed-by: Andrew Bonventre <andybons@golang.org>
To increase accessibility of the search bar, an aria-label for screen readers and a submit button was added. The search field was given the semantically correct input type and marked required field as hints to UAs that can use that to provide context to the user. The placeholder text was restyled for improved contrast. The javascript for handling placeholders was removed as it is no longer necessary. For golang/go#22171 Change-Id: I8db6428bb727a09e7f175e77100b4bcf9b6a5f3e Reviewed-on: https://go-review.googlesource.com/69190 Reviewed-by: Andrew Bonventre <andybons@golang.org>
There were two issues with links in godoc: 1) They were only distinguished from ordinary text only by color, affecting those with color-vision deficiencies. 2) The same blue used for links is used by non-links, affecting everybody. This change adds a an underline to all links. Usually, it is safe to skip underlining in locations where it clear that the only contents are navigational links, such as #pkg-index. However, (2) prevented this. To work around this I used some less well supported CSS techniques: http://caniuse.com/#feat=text-decoration Less capable browsers, which are unlikely to be used by developers, may have a less than optimal experience, unfortunately. In more capable browsers, including those without full support, the experience is quite pleasant and the additional underlying does not interfere with the godoc aesthetic. For golang/go#22171 Change-Id: I5a0d817793e8aa31912ba065b4e5a63d4a3f138c Reviewed-on: https://go-review.googlesource.com/69150 Reviewed-by: Andrew Bonventre <andybons@golang.org>
|
@jimmyfrasche IMO the underline effects in CL 69150 makes the docs look messy, especially in the package table of contents. I'm curious if anyone else feels that way.
|
|
@bontibon The purpose is to distinguish between clickable and not clickable elements. That means having to distinguishing them by both shape and color. This helps users who have trouble seeing certain colors, a monochrome display, and new users who haven't acclimated to the fact that you can click "func Count(s, substr string) int" but not "Package strings" despite them both being the same blue. |
|
I find the underlines fairly hard to read. Perhaps we should keep the underline, but make it an opacity of 30% or something. |
|
cc: @rsc I strongly agree with @bontibon: This new look is quite ugly in my mind. When we started on godoc, we made the deliberate decision to not have the underlines. Also, all the section titles now have a paragraph symbol at the end (see e.g. https://tip.golang.org/doc/). Overall, the graphic quality of golang.org has deteriorated significantly here. I am all for accessibility, but surely the answer is not to make golang.org less accessible for the majority of people. I'm taking part of the blame here since I gave the go-ahead signal but then didn't really look at the changes. Going forward, I suggest:
In summary, let's provide accessibility without compromising the vast majority of users. Thanks. |
|
I'd like to note that as a colorblind person with mild deutranopia and tritanopia, I find this much harder to read overall, despite the anchor tags standing out. In general, I'm not really a fan of using Are there any other approaches being considered here? If the goal is to distinguish links by not only color alone, a different font (like a fixed width font that stands out on a coding page) might be better suited. |
|
I'm going to respond out of order but try to hit everything. Please let me know if I missed anything. In the future, I will post in this thread with screenshots whenever I make a CL that changes visuals in any way so everyone knows that something unhappy is afoot. Other than these and a small contrast tweak here or there, there should only be one other as far as I can tell, though: visible hover/focus states for buttons and button-themed links. Regardless, I'll look forward to more thorough reviews. @griesemer The ever-present pilcrows (¶) are because if they're not always there's never a way to get to them to without using a mouse. In the first patch set, they were pushed further to the right and de-emphasized to counteract them always being visible. Even if that had made it, it looks like it wouldn't have meshed well with underlines and would require its own formatting. But for that matter they don't work with the toggled sections either. Maybe that feature needs more of a holistic re-think—that was certainly the minimal patch.
I don't have any vision or motor deficiencies that would make a lack of underlines on links troublesome for me. Generally, I think no underlines looks better, but there are more considerations to balance than just aesthetics. I'm not a fan of how it works on godoc. The headers and links being the same color, especially when all or part of a header is a link, means I have to guess whether something might be clickable and check by hovering over the link. I've been using Go a long time and by now I've roughly memorized everything that is and is not a link so it only shows up as sometimes clicking a header and realizing that it's not a link. It's as small as an inconvenience can get, but it's still irksome when run across. If I did have a motor deficiency and were new to Go, it could take actual effort and strain to position the mouse to check (which I would have to do until the keyboard accessibility is 100%). If I had total color blindness on top of that, I'd have to do that for every word in every page. It would not be a welcoming experience to the language.
I agree that the change that ended up being pushed is less than ideal. I think that the readability could be improved (see below) without as great an aesthetic impact.
A css file with for the visual issues would be quite small. The mechanism to enable that stylesheet would likely not be as small. And such a mechanism would of course itself have to be both accessible and easily discoverable or it would be of little use to those who need it. Like with any configuration option, it would require changes to be tested both with the accessible stylesheet enabled and disabled, except few will, so when there are any changes that need additional handling in the accessible stylesheet it will tend to lag behind the main stylesheet. A style that is readable and acceptable to everyone would be simpler and better for everyone. @dsnet The original CL for the underlines in fact had the underline color at 50% opacity to counteract the harsher interactions, particularly with the pkg-index:
Here's a variant with the text color at .3 opacity: Here's a dotted line as @paranoiacblack suggests. It may work better in conjunction with one of the above, this one is just the same color as the link: Unfortunately the only way to adjust the underline's position to the text is to fake it with it a border or box-shadow. That has a lot of edge cases and requires a bit of code to cover everything, but here's a very rough sketch using border. It does have its virtues and might work better with a transparent border and it would need some more spacing, as noted: Just to round out the options in case it gives anyone ideas, another tact is to attach an icon of some sort as a signifier, akin to the ▹/▾ used for collapsible sections: I'm not a designer by any means so if anyone has better ideas I'd love to hear them. |
If that's the rationale, we should use CSS and/or JS to detect mobile and display it permanently only in that situation. Given that Go is mostly developed on desktops or laptops with full browsers, it seems sensible to prioritize making sure things looks nice on that platform first. |
|
@dsnet it has nothing to do with touch (though that benefits as well) it's about people who can't use a mouse or find it difficult and all of the devices to aid accessibility that work by synthetic keyevent. |
|
Again, I am all for accessibility but we should do it right and not compromise one experience for a slightly improved experience for others. The result will not be satisfying for anybody.
I don't see why this mechanism is complicated. We serve the html which is generated via templates. It can't be too hard to replace the .css reference to a different one; perhaps based on a cookie. |
|
Sorry if I was unclear. I meant not just the mechanism to include the alternate stylesheet, but the mechanism in the user interface of the site allowing one to enable the alternate stylesheet. There are probably other configuration options that would eventually get exposed: maybe being able to set the default GOOS/GOARCH in addition to a per-package UI, as requested in #22178 . Not very useful when running a local godoc but I'm sure it could be handy for someone using tip.golang.org. Since it's a general settings page, it would probably suffice to have a gear icon in the navigation bar that goes to the settings page. If it turns into a grab bag, it won't be immediately apparent that you need to go there to turn on visual accessibility settings—few sites offer such choices, even in config so it's not something one learns to expect. It would be discoverable though and certainly better than nothing. If it stays focused on accessibility settings, a generic gear icon wouldn't be wrong but it would be sort of deceiving—everyone would click it to see what fun config parameters can be messed with. To make it clear that it is solely for accessibility settings, it should be so labeled. But having something named "accessibility settings" would take up quite a bit of real estate in the navigation menu, so it's going to get pushed down somewhere else. The label would be more appropriate but the overall discoverability would be worse since it would itself be harder to find. One compromise would be to put in the navigation bar but slightly out of the way: Another compromise would be to more selective about where to include visual indication and by having an appropriate variety of stylings based on context. Things like the package index could be considered sufficiently self-evidently navigation to be exempted. Links in headers could have their own appropriate style and links in general text areas another. |
|
We are looking to roll master to golang.org, so I’m going to revert the changes to the underlines and permalinks since those seem the most contentious. @jimmyfrasche please don’t interpret this as being unappreciative or dismissive of the work you’re doing, because we are very happy you’re doing it and this is very important work. Feel free to open another set of CLs (revert the reverts if you like) so that we can better discuss the design decisions with the relevant people. |
This reverts commit f57adc1. Reason for revert: See golang/go#22171 (comment) for reasoning. Change-Id: Ifd81ad716cf2acdf7a1d73602ac781186aca5596 Reviewed-on: https://go-review.googlesource.com/73150 Reviewed-by: Andrew Bonventre <andybons@golang.org>
|
Change https://golang.org/cl/73151 mentions this issue: |
This reverts commit 9bd2f44. Reason for revert: golang/go#22171 (comment) Update golang/go#22171 Change-Id: I41da526912b3484721782e0dad02d97ab2845a12 Reviewed-on: https://go-review.googlesource.com/73151 Reviewed-by: Andrew Bonventre <andybons@golang.org>
|
I just ran a google lighthouse test on the godoc page and we have a 97% score on accessibility.
I believe setting the lang attribute to "en" should fix it according to this site https://dequeuniversity.com/rules/axe/2.2/html-lang-valid. @jimmyfrasche - Any reason you have set the |
|
Lighthouse is the least useful a11y analyzer I've ever seen. I would recommend only using it if you need to triage major issues on an extremely inaccessible site, since that seems to be all it is concerned with. The SiteImprove chrome extension is the best one I've found (though it sometimes nags about signing up for their newsletter or somesuch, but that can be skipped). Even so, these are all static analyzers and, as such, while quite helpful, they have occasional false positives and many false negatives. Also, the criteria they're evaluating (WCAG) are necessarily a bit vague. The real test is if you can use the site exactly as well regardless of assistive technology or any temporary or permanent loss of ability. That is obviously quite hard to evaluate. In practice a good proxy for this is to:
It can be quite hard to get all of those 100% so the goal is to get them as close as is possible within reason. I marked the lang tag as hard because while the language of the document itself is en, the language of a given's documentation need not be. |
|
Thanks. But isn't the lang attribute supposed to contain the language of the document ? Or are you saying that there are translations of godoc, in which case the lang attribute needs to be dynamically set or sth ? |
|
Godoc can display arbitrary user packages. The site will be in en but the documentation for a given package might be de or ja or anything else. I am unsure if there would be side effects from not also marking those correctly. To even attempt to mark them correctly would require some kind of program to analyze the docs and guess the language or an out of band way to specify the BCP 47 tag of a package. |
|
Got it. Thanks for the clarification. |
ianlancetaylor
added
the
NeedsInvestigation
agnivade
changed the title
gopherbot
added
the
Tools
The gopher with a miner hat on /pkg had no alt attribute so screen readers would announce the image by its filename. As the image is purely decorative, adding the empty string as alternative text prevents the image from being announced. For golang/go#22171 Change-Id: Ib214f296d3d9f9084c44d4e33d1cbe432f2183ed Reviewed-on: https://go-review.googlesource.com/69130 Reviewed-by: Ian Lance Taylor <iant@golang.org>
The heading of the #pkg-index section of package documentation pages uses an h2 heading but its 'Examples' and 'Package files' subsections use h4 headings, skipping the h3 level. This change switches the h4s to h3s and adds styling to preserve the current font-size with the new heading level. For golang/go#22171 Change-Id: Ifd2cacab22c1e82fd6f061b9322523fa5859a80f Reviewed-on: https://go-review.googlesource.com/69171 Reviewed-by: jimmy frasche <soapboxcicero@gmail.com> Reviewed-by: Andrew Bonventre <andybons@golang.org>
This CL makes permalinks accessible to keyboard-users and screen readers. Adding an aria-label to permalinks overrides the default content of "pilcrow". As the permalinks only showed on hover they were inaccessible to users who could only use a keyboard and are now always shown. For golang/go#22171 Change-Id: I6ce3828dfedfd7edc29dd16f3eb94a0abcabfc7c Reviewed-on: https://go-review.googlesource.com/69210 Reviewed-by: Andrew Bonventre <andybons@golang.org>
To increase accessibility of the search bar, an aria-label for screen readers and a submit button was added. The search field was given the semantically correct input type and marked required field as hints to UAs that can use that to provide context to the user. The placeholder text was restyled for improved contrast. The javascript for handling placeholders was removed as it is no longer necessary. For golang/go#22171 Change-Id: I8db6428bb727a09e7f175e77100b4bcf9b6a5f3e Reviewed-on: https://go-review.googlesource.com/69190 Reviewed-by: Andrew Bonventre <andybons@golang.org>
There were two issues with links in godoc: 1) They were only distinguished from ordinary text only by color, affecting those with color-vision deficiencies. 2) The same blue used for links is used by non-links, affecting everybody. This change adds a an underline to all links. Usually, it is safe to skip underlining in locations where it clear that the only contents are navigational links, such as #pkg-index. However, (2) prevented this. To work around this I used some less well supported CSS techniques: http://caniuse.com/#feat=text-decoration Less capable browsers, which are unlikely to be used by developers, may have a less than optimal experience, unfortunately. In more capable browsers, including those without full support, the experience is quite pleasant and the additional underlying does not interfere with the godoc aesthetic. For golang/go#22171 Change-Id: I5a0d817793e8aa31912ba065b4e5a63d4a3f138c Reviewed-on: https://go-review.googlesource.com/69150 Reviewed-by: Andrew Bonventre <andybons@golang.org>
This reverts commit 6350066. Reason for revert: See golang/go#22171 (comment) for reasoning. Change-Id: Ifd81ad716cf2acdf7a1d73602ac781186aca5596 Reviewed-on: https://go-review.googlesource.com/73150 Reviewed-by: Andrew Bonventre <andybons@golang.org>
This reverts commit 0c379ae. Reason for revert: golang/go#22171 (comment) Update golang/go#22171 Change-Id: I41da526912b3484721782e0dad02d97ab2845a12 Reviewed-on: https://go-review.googlesource.com/73151 Reviewed-by: Andrew Bonventre <andybons@golang.org>
|
godoc is deprecated. |
This is a meta issue for improving the accessibility of godoc.
If you discover an issue not in the above list, please report it here so that it can be addressed.
If you want to help out and aren't sure where to start or just want to make sure that tools you create are as accessible possible, see (or update!) WebAccessibilityResourcesAndTips on the wiki.
The text was updated successfully, but these errors were encountered: