Review of explainers

I looked at the explainer in the wiki - referred to as TAG explainer at https://github.com/w3c/personalization-semantics/wiki/Explainer-for-Personalization-Semantics <https://github.com/w3c/personalization-semantics/wiki/Explainer-for-Personalization-Semantics>

I compared this to our draft explainer at https://w3c.github.io/personalization-semantics/ <https://w3c.github.io/personalization-semantics/>

The documents have different levels of detail.

I believe that the Abstract for the draft explainer is a bit too focused on converting to symbols and that the TAG explainer is more generic.   I believe we should update the abstract of the draft explainer.  Below is my suggestion slightly modified from the TAG explainer:

People have very different needs. Some people cannot process numeric information (dyscalculia), but others understand numbers better than words. Some people with severe language disabilities use symbols to represent words; some people need (or want) simplified user-interfaces. One of the main challenges is transforming content for these different needs.

This specification is designed to enable authors to add extra semantic information about content to enable personalization for the individual user, including providing extra support and enabling user agents for people with learning and cognitive disabilities.

Authors will be able to add extra semantic information using a collection of new attribute(s) and values, with (in most cases) a fixed token list (taxonomies). This document is an explanation for understanding how to use Personalization properties to personalize an accessible web site.

I also have suggestions about how to better format the Why do We Need Personalization section. There was a fair amount of repetition. I reorganized the bullets a bit:

Why We Need Personalization
We need personalization because: 
- Enable websites to adapt to and meet the user's needs.  The goal is to give users the ability to decide what works best for them based on preference and ability.
 — The needs of an individual user may conflict with certain established mainstream user-patterns.
 — Learning new design patterns, widgets, and user interfaces can be confusing.
- Ability to increase or decrease levels of complexity as people's skills improve or decline over time. Extra support can be a distraction for some while it may be critical for others.
- Provide extra support to users who may need:     
 — Symbols, iconography and graphics that they are familiar with
 — Tooltips or similar on-demand help or clues
 — Language they understand
 — Fewer or more constrained features
 — The ability to programmatically distinguish between native content and third-party content on a page or screen</li>
 — The ability to implement custom keyboard short cuts at the user-end

I did make these changes in a branch, explainer-compare, but I don’t know how to generate a URI to view a branch.  I also was not able to test  this locally because I haven’t been able to get my local web server to serve from an alias.  My server breaks every time Apple updates OSX. 

There are fairly major differences between the two explainers.  The TAG explainer has much more detail and examples with code.  I don’t believe we need this in the draft explainer but the group should discuss. 

The TAG explainer has a GOALS section that is not included within the draft explainer.

The location of section 1.4 Technology Comparison Summary seems odd within the Introduction section.  I believe it would make more sense after the discussion around the use of data- which happens in section 4. Vocabulary Implementation. 

The Use Cases are different between the two documents. 
The draft explainer includes a few use cases and then references the Use Cases on the Wiki at https://github.com/w3c/personalization-semantics/wiki/Use-cases <https://github.com/w3c/personalization-semantics/wiki/Use-cases>
The TAG explainer includes all of those use cases within the document and includes images and code.  Do we want that much detail within the draft explainer? 


-becky


Becky Gibson | Sr. Accessibility Strategist
Knowbility.org
becky@knowbility.org
Pronouns: she/her/hers