Web accessibility changes
smalers opened this issue · comments
The State has indicated that documentation needs to be updated for ADA compliance. The following are specific changes.
Update CSS to underline links
This is needed for people that are colorblind because they may not be able to see that links are colored. The necessary CSS for MkDocs custom CSS file is:
a:link {
text-decoration: underline;
}
Question: Does the underline need to be in black so that it is visible? Underlining in the same color does not address the original visual issue.
Add human-readable alt text for images
This is needed because readers that convert HTML to spoken language need to be able to describe the image, This accommodates people with blindness.
I have been instructed that the alt text should be the same as the caption associated with the image.
Question: Do the readers read the alt text and then also read the caption under the image, which is often just centered text? If so, then a blind person would hear redundant words.
Make sure there are no empty sections
This is perhaps not an ADA thing?
TSTool command documentation often has empty Troubleshooting sections and sometimes also See Also. I'd like to keep the sections consistent so that users can expect that consistency. My suggestion is just to link to the main TSTool troubleshooting page and I can probably always find something to put in See Also.
Q1 A1: The underline for link text does not need to be black. The underline itself is the indicator to someone with color issues that there is a clickable link there.
Q2 A2: You are correct that the caption will also be read. A truncated, but descriptive alt text can be used instead. For example, if the image is of a main interface and the png filename is "MainInterface", then the alt text could be "Main Interface". The JAWS reader will read "Main Interface Graphic" to the user.
No Empty Sections is not a WCAG requirement, however, it is still an accessibility issue, and one that does affect our score within SiteImprove. Here's what SI says about the topic:
"Headings structure content in an accessible way. They should be organized in a logical hierarchy so that screen reader and keyboard-only users can easily understand and navigate content.
Content should appear as expected including between headings of the same level and after the last section or page heading. If content is missing then the user does not know if the information is hidden, or if a heading level was applied incorrectly."
Additional WCAG items to fix
Structure Headings
Headings should flow in a logical order: The rule of thumb is, don't skip heading levels - only increase by 1. So you can repeat the same heading level, increase the heading level by 1 or decrease the heading level. So the following would be valid examples:
H1
-- H2
-- H2
-- -- H3
-- H2
or
H1
-- H2
-- -- H3
-- -- H3
-- -- -- H4
-- H2
-- H2
This would be invalid
H1
-- H3 (shouldn't skip from H1 to H3)
-- H2
-- H2
-- -- H4 (Shouldn't skip from H2 to H4)
###Missing Closing list tags
Container Element is Empty
There are some instances where a list within a table is missing a closing tag, resulting in a blank list item in the code for the webpage. Pages with this issue are listed in SiteImprove under Accessibility>Container Element is Empty
For underlines I guess it makes sense. The color may still be hard for someone to fully see but if they can see the underline in some form they know it is a link.
For image alt text is it enough to say, for example, "Command editor" (so it will read as "command editor image"). Using the full name such as "ReadHydroBase command editor" is more descriptive but perhaps unnecessary given that the command name will have been read elsewhere and the scoring probably won't care. I can add more detail if there are multiple images such as tabs on an editor.
As for the headers and closing tags, responding to specific reports on this will be necessary so I'll try to review the SiteImprove output. There is a lot of TSTool documentation and such things may occur.
Alt text needs to be unique on a page (relative to other alt text), so multiple images can't just say Command Editor. The scoring will put that up as a separate issue. In all of the StateDMI images on the commands pages, I typically added "command editor" to the alt text so that it did end up being like "ReadHydroBase command editor".
There are less than a dozen TSTool pages each with issues for headers and closing tags, so it shouldn't be as big a deal as the StateDMI command pages were where every page had a header issue.
I added the underline for links.
I added to all the troubleshooting sections.
I am now working through the alt text when I can stand it. One issue came up. On the release notes I use the same image many times, for example to show a bug icon. What do I do in that case? Here is an example. It seems like the site checker needs ways to exclude certain pages or files because it is just noise.
*  [11.13.00] Datastore configuration files for USGS NWIS and NRCS AWDB web services have been changed to use https URLs based on changes in the web services.
I finished updating the alt text for images for all content. See the following:
https://opencdss.state.co.us/tstool/14.7.0/doc-user/
As far as I know I am done with the updates other than the release notes icon issue above. Once I know what to do with that the documentation will be done. I need to run the automated tests on 14.7.0 and then I can release.
I added the underline for links.
I added to all the troubleshooting sections.
I am now working through the alt text when I can stand it. One issue came up. On the release notes I use the same image many times, for example to show a bug icon. What do I do in that case? Here is an example. It seems like the site checker needs ways to exclude certain pages or files because it is just noise.
*  [11.13.00] Datastore configuration files for USGS NWIS and NRCS AWDB web services have been changed to use https URLs based on changes in the web services.
So it's the same image every time? Then don't worry about changing it.
OK, then the TSTool documentation is ready for deployment once I do testing on 14.7.0 and can make a release to the OpenCDSS website.
Yes, the release notes will use "bug", "change", "new", etc. many times on a single page.
Carolyn, can you paste the SiteImprove URL here for where I would look for those specific issues with TSTool sections and closed tags? Or email me. Then I can fix those.
Also, is there a way to embed something in the HTML to cause the site checker to ignore a page, or ignore specific checks on a page, for example the redundant alt text in release notes? It does not seem like the type of check can be configured/excluded at a page level. However, it does seem like entire pages and trees can be excluded from the crawl, such as old documentation releases can be excluded so that we can focus on recent and current documentation going forward. Someone at the State would need to configure that.
Also, the web pages look busier with the underlines. There is no way around that. I'll get used to it over time.
Carolyn provided me with the SiteImprove link to fix empty elements and I did that. If there are any other loose ends I can follow up. I'll ask whether I should publish to "latest" so the software will review.
I'm closing this issue. Documentation has been updated for accessibility.