Re: [w3ctag/design-reviews] Personalization Semantics Explainer and  Module 1 (#476)

Hi Lisa et al,

Thank you for bringing this work to us.

@torgo, @atanassov and I have had a chance to go through the explainer in our face to face meeting in Wellington. Unfortunately, we were unable to understand from the explainer what the proposed technology/API is.

Would it be possible to have a document more closely based on our [Explainer template](https://w3ctag.github.io/explainers#explainer-template)?

Specifically:
- The explainer document should contain no boilerplate - it is an informal document, we don't need to know its formal status
- The explainer should start with a brief (2-3 short sentences) summary of the proposed technology
- It would be nice to have some concrete, specific examples of user problems - the Use Cases section does cover some user problems, but it's difficult to understand where one example ends and another begins. 
   - Adding sub-headings to briefly describe each user problem/need would be helpful
   - The "send email" button example is interesting, but we couldn't really follow it - some mock-ups of different presentations would be helpful
   - The section on Symbols was similarly tricky to follow for someone who is unfamiliar with the topic. It would be helpful if it was more succinct, and potentially included some screenshots or mock-ups  
- The "Technology Summary" should be framed in terms of "Considered alternatives", and included later in the document (and we weren't sure what things like "Authoring" were doing in that list)
- The proposed solution/solutions should be described clearly and with exampled (including example code) framed around the user needs described.
- The Vocabulary Structure section is unnecessary in this context, as is Stakeholders

It seems like perhaps this needs to be three smaller explainers, one for each module, possibly with one meta-explainer framing the larger picture?

We were left unclear on what the actual proposed technology was - the Explainer or Explainers should clearly explain the proposal, without requiring the reader to click through to supplementary material. Supplementary material may go into extra detail or more technical depth.

We are excited for this work, and would like to help review the proposal, but we were left scratching our heads a bit here - we hope the above feedback helps explain what would be more useful for us.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3ctag/design-reviews/issues/476#issuecomment-594853146