w3c/adapt

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-* 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)