Explainer - Content Issues
matatk opened this issue · 2 comments
https://w3c.github.io/personalization-semantics/
I finally took the time to read right through it and it's a great intro.
I'd be happy to have a go at making a PR/PRs for any/all of these—please let me know if you'd like me to.
I filed a related issue on more editorial things: #178
Abstract
- "This specification provides a means for web technologies to address these requirements." - is that right? Shouldn't it refer to the specs described by the Explainer?
- "This document is an explanation for understanding how to use Personalization properties to personalize an accessible web site." - isn't this more of the why and the spec the how?
§1 Introduction
- Regarding: "Expands the accessibility information supplied by the author;"—is it meaning that we imagine the author is already providing some accessibility info (explicitly or implicitly by using semantic elements etc.) and the attributes in the Personalization Semantics spec build upon this? If so, could we say something like: "Expands upon the types of accessibility information that the author can supply" [or "provide"] or something similar along the lines of building upon any info they're already providing?
- Does "and keyboard." mean keyboard shortcuts?
§1.2.1 Easily Distracted / Overwhelmed
- The example references the "data-simplification" attribute but the attribute hasn't been introduced yet. Suggest adding some "run up" phrasing before the attribute name (and making it a link to later?)
§1.2.2 Difficulty Understanding Numbers
- Suggest making it clear that data-numberfree is an attribute (i.e. include "attribute" after it).
§1.2.4 Severe Language Impairment
- The description of the example and the example code don't seem to match up (the description mentions sending an email, but the code is about labelling a home address).
- "However, the various vocabularies are mutually unintelligible." - not sure what this is saying; is it one/all of the below?
- Different symbol sets have the symbols for the same concepts, but they look different.
- Different symbol sets may not have symbols for the same underlying concepts.
- other
Would something like "However, the various vocabularies are not interchangeable." be correct?
§1.2.5 Working Memory and Short-term Memory Impairment
- Wondering if there will be some dev concern about how this relates to things like
aria-current- not sure we need to elaborate here; I'm going to be reading the actual spec next... :-)
§1.3 Out of Scope
- The wiki is mentioned but there's not a link to it.
§3.2 Values
- Does the "default" value mean the implied value when the attribute is not present? If so, I think there may be a specific W3C word for this [if it's not "default"], which I've seen in other specs; need to look it up...
§4.1 Current usage
- The URI we have is a W3C one that redirects to https://www.w3.org/TR/html5/dom.html#embedding-custom-non-visible-data-with-the-data-attributes but this is wrong, as there's an asterisk and extra hyphen in the real URI, which is: https://html.spec.whatwg.org/multipage/dom.html#embedding-custom-non-visible-data-with-the-data-*-attributes
- Our link text in that link should include the asterisk after "data-" so as to match the referenced content (and to be clear that it represents many possible attributes).
- There's a "NOTE" box lower down that repeats the part about using data-* attributes, and provides the correct URI for reference so maybe best to just delete the first link from the first paragraph anyway?
- Not sure "name value pairs" is the right term for the list here, as the list is of the attribute names. I wonder if it's best just to call them attributes?
- It should be "WHATWG" as opposed to "WHAT-WG".
§4.2 Technology Comparison Summary
- There are two separate lists here; the second is preceded by an empty
<p>but it seems like there should be some introductory text here. I think it would likely be about the requirements for the chosen approach?
We discussed this on the call yesterday and decided to split out the issues reported here as separate GitHub issues, which I will do as soon as I'm able.
(We decided not to do the same thing with the editorial issues, as they should be simpler to address.)
Editorial changes made and pull request submitted.
One outstanding issue related to 'default values' - email sent 2021/4/20