tidoust
commented
2 years ago Thanks for the comments @matatk!
I prepared a couple of pull requests accordingly.
§1 - The new page describing the flowchart diagram (which 404s from the current version of the spec, but is present in the Editor's Draft) is really good
PR #308 would fix the 404. I'll let spec editors update the description as needed.
§2, 4 - The enumeration description tables have two visually apparent columns, but only a single header that spans both columns. Consider either providing two separate column headers, or coding this as a definition list.
PR #309 uses separate column headers and adds table captions. I note that this is one of these patterns that some spec started and other specs adopted. I ran a quick analysis on specs (looking for table headers that span multiple columns and have "enumeration" in their label, see below for code I used) and found the same issue in the following specs:
- 1 found in MediaStreamTrack Content Hints
- 1 found in Identity for WebRTC 1.0
- 1 found in WebRTC Priority Control API
- 2 found in Autoplay Policy Detection
- 3 found in Screen Capture
- 4 found in Media Capture and Streams
- 4 found in Identifiers for WebRTC's Statistics API
- 5 found in Encrypted Media Extensions
- 10 found in Web Audio API
- 21 found in WebRTC 1.0: Real-Time Communication Between Browsers
If fix looks good, I'll try to propagate it to other specs. The above list may not be exhaustive.
Code used to detect problem in specs
1. Create an `enumerations.mjs` file with the following content: ```js export default function () { return [...document.querySelectorAll('th[colspan]')] .filter(th => th.textContent.trim().toLowerCase().includes('enumeration')) .length; } ``` 2. Run [Reffy](https://github.com/w3c/reffy) to analyze all specs, with a bit of `jq` magic to format the results: ```bash reffy -m enumerations.mjs | jq -r "sort_by(.enumerations) | .[] | select(.enumerations) | (.enumerations | tostring) + \" found in \" + .title + \" - \" + .crawled" > result.txt ```§2.2, 4.2, 5.2 - Parameter definition tables
PR #309 uses row headers for parameter names. Styles were wrong because they used to be provided out-of-the-box by ReSpec and this table pattern for parameters is no longer supported by default. The pull request re-introduces the old styles, which should address your concerns.
§3.5.12 - The image representing the algorithm lacks a description.
I'll let spec editors handle this :)
§4, 6.1, 6.2, 7, 8, 9 - The "agenda" tag has very low contrast
The background color for the label comes from GitHub. The color itself is incorrectly computed by ReSpec. I reported the issue on ReSpec (see https://github.com/w3c/respec/issues/4139) and changed the background color on GitHub for the "agenda" label. Fix will appear next time the spec is re-generated (e.g. when one of the PRs gets merged).
wolenetz
I'm co-chair of the Accessible Platform Architectures (APA) WG. We are currently reviewing your specification for any accessibility concerns. However this is a personal comment concentrating on editorial accessibility issues and suggestions for the document. As these are editorial in nature, I am filing them all under one issue; hope that's OK.
We can provide further info and suggestions if that would help. Also, we recognise that you may be aware of some of these already and, for example, be in the process of updating image descriptions.
Our technical review will follow. Here are the editorial accessibility concerns, with the sections they appear in (may not be exhaustive)...
§1 - The new page describing the flowchart diagram (which 404s from the current version of the spec, but is present in the Editor's Draft) is really good, though there are several small mismatches between the description and the diagram in its current version.
§2, 4 - The enumeration description tables have two visually apparent columns, but only a single header that spans both columns. Consider either providing two separate column headers, or coding this as a definition list.
§2.2, 4.2, 5.2 - Parameter definition tables
§3.5.12 - The image representing the algorithm lacks a description. It's acknowledged that the image is itself a graphical representation of the algorithm described above it, but looks like it's a particularly concrete example, and it has specific features that should be described to help people interpret it. Another way to phrase this would be that the image isn't what I had in mind when reading the algorithm (though that may be due to lack of experience). For example, there are vertical lines and gradients at specific times in the image. It seems like a separate description may be warranted.
§4, 6.1, 6.2, 7, 8, 9 - The "agenda" tag has very low contrast (it's black text on a dark red background). It doesn't seem that this will be in the final spec, but either way if it's possible to address it, that would be helpful.
Please let us know if you have any concerns and/or would like help addressing any of the above.