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-* and aui-* (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)
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
§1.1
§1.2.1 Easily Distracted / Overwhelmed
"<section>, <p> or <div>"
are marked up as being code.§1.2.2 Difficulty Understanding Numbers
§1.2.3 Mild-Moderate Language Impairment / Learning Disability
§1.2.4 Severe Language Impairment
§1.2.5 Working Memory and Short-term Memory Impairment
§2 Modules
§4.1 Current usage
§4.2 Technology Comparison Summary
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.§5. Stakeholders