Explainer - Editorial Issues
matatk opened this issue · 0 comments
matatk commented
https://w3c.github.io/personalization-semantics/
I finally took the time to read right through it and, as mentioned in #177, 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 substantial content issues (which may override some of the below):
§1 Introduction
- Suggest "preference-driven" (i.e. with hyphen)
§1.1
- Here it says "short cuts" but later in this section it says there's a "shortcut"
- "Example of sending an email" - should be in a formatted box?
§1.2.1 Easily Distracted / Overwhelmed
- Should the example paragraph be in a specific box?
- The commas and "or" within the list
"<section>, <p> or <div>"
are marked up as being code. - "data-simplification" not marked up as code
- Lower-case the C of "Content re-ordering" as it's not the start of a new sentence?
§1.2.2 Difficulty Understanding Numbers
- Should the example paragraph be in a specific box?
- "data-numberfree" isn't marked up as code.
§1.2.3 Mild-Moderate Language Impairment / Learning Disability
- Should the example paragraph be in a specific box?
- Looks like a parsing error on the text that's intended to be in italics.
- Should the line of code be in a Code example box?
- "numberfree" isn't marked up as code, nor does it have the "data-". Maybe "number-free" (not referencing the attribute) is better?
§1.2.4 Severe Language Impairment
- Suggest "User stories" instead of "User-stories"
- Suggest "symbol set*" instead of "symbol-set*" (both terms are used in the document).
- The para about the "data-symbol" attribute just begins with "data-symbol: " which seems a bit jarring, and I don't think is needed as the attribute is introduced immediately in that sentence.
- Should the line of code be in a Code example box?
- Feels like maybe "Proof of Concept Symbol Example" should be a subheading.
- Need a figure with caption for the images.
- Should the images' sizes be constrained by CSS? They're wider than my screen. Not sure about this.
§1.2.5 Working Memory and Short-term Memory Impairment
- Should the example paragraph be in a specific box?
§2 Modules
- Adaptable content's starting text is "This section provides" but it seems like "This module" would be more apt?
§4.1 Current usage
- Suggest "name-value" instead of "name value" and I wonder if the term should be "key-value" (perhaps "name-value" is the W3C standard though, not sure).
§4.2 Technology Comparison Summary
- Think we should have
aria-*
andaui-*
(marked up as code) if we're referring to the actual attribute names (or possible names) or we could just have "ARIA attributes" instead. Currently we have a mix of the two styles. - Each of the items in the second list (which I think are requirements for the chosen approach) feels like it should start with a term in bold.
- "The details of our research and discussion is documented" should be "are" instead of "is" (details plural).
- "See the Vocabulary Implementations section in the Explainer document for further details on the use of data- attributes." - should say "above" as we're in that document?
- Also it should say "data-*" attributes for consistency.
§5. Stakeholders
- The first bullet point only ends with a full-stop. I am not sure about the other bullet lists in the document.
- "we suggest including a link to an extension an implementation that can maximize" - remove "extension an"? (seems redundant)