Personalization Help and Support 1.0

W3C Editor's Draft

This version:
https://w3c.github.io/personalization-semantics/help/
Latest published version:
https://www.w3.org/TR/personalization-semantics-help-1.0/
Latest editor's draft:
https://w3c.github.io/personalization-semantics/help/
Editors:
(Benetech)
(W3C)
(W3C)
Richard Schwerdtfeger (Knowbility) (Editor until October 2017)

Abstract

This document list examples of the personalized help and support properties, this is an extension of Personalization Explainer 1.0. including the properties of literal, numberfree, easylang, alternative, explain, feedback, moreinfo,extrahelp, helptype.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the Accessible Rich Internet Applications Working Group as an Editor's Draft.

Comments regarding this document are welcome. Please send them to public-personalization-tf@w3.org (archives).

Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 February 2018 W3C Process Document.

1. Introduction§

This section is non-normative.

This document list examples of the personalized help and support properties, this is an extension of Personalization Explainer 1.0. including the properties of literal, numberfree, easylang, alternative, explain, feedback, moreinfo,extrahelp, helptype.

Editor's note

Personalization semantics defines a set of properties and values to annotate content. The specific mechanism to apply these properties to content has not been decided. Several approaches are under consideration and future drafts will show progress. To help with understanding of the properties, this document provides many examples of personalization semantics applied to content, which show attributes beginning with the prefix "aui-". This has not been decided as the chosen approach, but the simplicity supports understanding of the examples.

2. Use Cases§

2.1 Number Free§

Requirement: Not everyone can understand numbers. We therefor suggest numberfree for alternative text for people who can not understand the main content

User experience:

A suggested user experience would be: Numerical concepts could be rendered by the user agent slightly different so that the user knows a number free explanation is available. The user can then mouse over the content and a tooltips would give the number free value

Relevant properties: numberfree

2.2 Language Type Support§

Requirement: Sometimes you may want to provide a simplified version of a section of a page. For example, you may wish to provide a simplified summary of legal document, but still have a longer version for other users. These alternative versions may not be identical in content but maintain the gist of the original content.

Relevant properties: alternative, easylang

2.3 Non-literal Text and Images§

Requirement: Not everyone can understand non-literal text and icons such as metaphors, idioms etc. We need a tag that identifies text or images as non literal and allows the author to explain non-literal text and images to users.

User experience:

A suggested user experience would be: Non literal content could be rendered by the user agent slightly differently so that the user knows that this content should not be taken literally and that a literal explanation is available. The user can then mouse over the content and a tooltips would give the literal value.

Relevant properties: literal

2.4 More Help§

Requirement: Some users may need additional information or specifically additional help information. We request additional attributes so that an author can indicate the existence of this additional information.

Relevant properties: moreinfo, extrahelp, helptype

2.5 Explain and Feedback§

Requirement:

Some users need additional help. We request an attribute where the author can provide additional information or what just happened.

Relevant properties: feedback, explain

2.6 Potential Features§

The following may not be necessary

3. Vocabulary §

3.1 vocabulary§

3.1.1 Description§

The following are terms used to describe alternative or supportive content that may be useful for people with disabilities. The current list focuses on cognitive disabilities, hover we intended to merge the vocabularies for other disabilities in the next version.

Overview of supported values:

  • On text: active, chunks, dictionary, easylang, explain, faqs, glossary, humanhelp, literal, moreinfo, numberfree, simplified, smallsentences, thesaurus, vocab500, vocab1000, vocab2000
  • General: alternative, automated, helpforms, largefont, lessoptions, symbolic, whitespace
  • Images: p0, p1, p2, p3, realistic, symbolic

Note that there is no default value.

3.1.2 Values for alternative content and content accessibility support§

Editor's note
This focuses on cognative accessibility. We may add other collections from https://github.com/w3c/personalization-semantics/wiki/User-needs-collections such as https://www.w3.org/wiki/WebSchemas/Accessibility.
.
Value Description
active
chunks breaks the content up in to smaller secions with a single topic per section.
easylang provides a rewrite of the content using short sentences and simple language.
explain provides a more detailed description of a process or term.
extrahelp additional information about the current action or process in one or more formats.
feedback provides and identifies immediate information about any action that occurs.
largefont
lessoptions provide fewer choices by combining related choices together
literal provide the literal translation of existing casual language or idioms
numberfree provides a version of the content that does not use numbers.
p0 images with true content
p1 symbol or illustration that is typically shown with alt=""
p2 extra illustration that will not distract most people such as at the start of a paragraph or option
p3 disability centric illustrations that can disturb other people and may be mid sentence.
realistic provides a realistic version of a stylized or cartoonish (not real) image.
simplified Provides, a version of the content that is easier to read and understand.
smallsentences provides a version of the content with shorter sentences and simple language.
symbolic provides an alternative, symbolic representation of an image, for example a picture rather than a photograph.
vocab1000
vocab2000
vocab500
whitespace add additional whitespace between characters, words, and rows.

Values for types of help §

Editor's note
This may be added to or harmonized with link destinations in module 1. Or it may be added to the above table.
.
Value Description
automatedStep provides an alternative step by step sequence for completing a task or procedure.
automatedBot provides an automated conversational help. Typically designed to look like human help.
dictionary provides a definition of the term or topic. May redirect to another uri or provide the information in-line, via a popup, or other method.
faqs redirects to a FAQ page with the related topic in view.
glossary provides a uri to a glossary page with the related topic in view.
helpform Used with forms when the user may need more or simplified information about the type of information being requested. Provides with a modified form with more information about each requested item.
humanhelp Provides the user with access to human help. This may be through a live chat, providing a phone number to call for human assistance, or other mechanism to reach a person for direct assistance.
morehelp Provides a more detailed explanation about the current topic or process.
moreinfo provides additional levels of detail.
simplified propose this should be easylang rather than simplified. Provides, a version of the content that is easier to read and understand.
thesaurus provides a list of synonyms for the current term. May redirect to another uri or provide a list of synonyms in-line, via a popup, or other method.
tooltips offers an option of adding tooltips to provide morehelp with more detailed information about the current topic or process.
topicsearch provides a uri for the user to perform a search on the current topic with the suggested search term included.
3.1.2.1 Characteristics§
Characteristic Value
Related Concepts:
Used in Roles: All elements of the base markup
Inherits into Roles: landmarks and regions in Divs and sections,, alternitive (in headers) some cases alt text
Value: token list

4. Example Implementations§

There are two proposed general methods to implement the help and support. The first provides help and supporting content in a different section of content. For small changes, the additional information and support can be provided inline with the content.

Editor's note

Currently all examples are implemented via attribute/value pairs. This does not imply that attribute/value pairs are the only implemenation strategy. The Working Group plans to add additional examples using other mechanisms.

4.1 Implementation in diffrent content sections§

4.1.1 Alternative§

4.1.1.1 Description§

Would be used on an alternative content as an alternative to more detailed or difficult to understand content. alternative can be used on a span, div, link or image that servers as alternative content to it's direct parent element.

Editor's note

This data model may be too complex, so this property could undergo substantial changes.

Supported values:

  • On text: easylang, explain, more, vocab500, vocab1000, vocab2000, active, literal, numberfree, smallsentences, chunks
  • General: lessoptions. Whitespace, largefont 
  • Images: symbolic , realistic
  • p0, p1, p1, p2, p3 Where p0 are images with true content, p1 is a symbol or illustration that is typically shown with alt="", P2 are extra illustration that most people will not mind such as at the start of a paragraph or option. p3 are for disability centric illustrations that can disturb other people and may be mid sentence. 

Note that there is no default value.

4.1.1.2 Example§

The below example section show how alternative used when coding.

Example: Alternative Using ARIA
<div>
	<span aui-alternative="easylang numberfree vocab1000" class="hidden">
 	   most people prefer simple text
  	</span>
        In studies it was found that only 30% of users prefer long convoluted text
  	with obtuse words and lots of numbers,
  	with 56% claiming there preferred the simplified text,
  	with the remainder unsure or stated it depends on the context.
</div>
4.1.1.3 Characteristics§
Characteristic Value
Related Concepts:
Used in Roles: All elements of the base markup
Inherits into Roles: Placeholder
Value: token list

4.1.2 helptype§

4.1.2.1 Description§

Would be used on additional content to indicate the type of extra help provided. helptype can be used on a span, div, link or image that provides or redirects the user to additional help information.

Overview of supported values:

  • On text: dictionary, faqs, glossary, humanhelp, literal, morehelp, simplified, thesaurus, vocab500, vocab1000, vocab2000
  • General: automated, helpform, largefont, lessoptions, symbolic, tooltips, whitespace
  • Images: p0, p1, p2, p3, realistic, symbolic

Note that there is no default value.

4.1.2.2 Example§

The below example section show how helptype used when coding.

Example: Helptype Using ARIA
<button type="button" aui-extrahelp="uri2 uri3" >undo</button>

URI 2 may read:

<div id="uri2" aui-helptype="morehelp" aui-hidden="true">
  pressing the undo button will erase all your work on this page.
  Use this button with care.
  If you press it by mistake, press control and y at the same time
  and your answers will come back.
</div>

<a href="functiongethelp()" aui-helptype="humanhelp" aui-hidden="true">
  I want a person to help me</a>

<div id="uri3" aui-extrahelp="glossary" aui-hidden="true">
4.1.2.3 Characteristics§
Characteristic Value
Related Concepts:
Used in Roles: All elements of the base markup
Inherits into Roles: Placeholder
Value: token

4.2 Implementation Inline§

For small inline support and changes, attributes may be used.

4.2.1 literal§

4.2.1.1 Description§

literal provides alternative text for people who prefer content that does not use non literal text, such as metaphors.

A personalization agent may replace the content with the literal alternative, or it may put the literal alternative in a tooltip.

User agents may also render non-literal text in a different way so that users will be able to identify non literal content. They can then use a mouse over or other technique to receive the alternative.

A user agent must be able to replace the non literal content with the literal alternative without loss of meaning.

Supported value: String

Note that there is no default value.

4.2.1.2 Example§

The below example section show how literal used when coding.

Example: Symbol Using ARIA
It is <span aui-literal="raining hard">raining cats and dogs</span>
4.2.1.3 Characteristics§
Characteristic Value
Related Concepts:
Used in Roles: All elements of the base markup
Inherits into Roles: Placeholder
Value: string

4.2.2 numberfree§

4.2.2.1 Description§

numberfree provides alternative text for people who prefer content that does not use numerical concepts.

A personalization agent may replace the content with the number free alternative, or it may put the number free alternative in a tooltip or sidebar. The content must still be understandable when a user agent replaces the original content with the number free alternative.

Supported value: String

Note that there is no default value.

4.2.2.2 Example§

The below example section show how numberfree used when coding.

Example 1: Numberfree Using ARIA
<span aui-numberfree="almost all">9 out of 10 </span>
Example 2: Numberfree Using ARIA
<span aui-numberfree="hat and coat weather">The weather is 9 degrees</span>
4.2.2.3 Characteristics§
Characteristic Value
Related Concepts:
Used in Roles: All elements of the base markup
Inherits into Roles: Placeholder
Value: string

4.2.3 easylang§

4.2.3.1 Description§

easylang provides an alternative text of the content that is easier to read and understand. Note that this only works on small sections of text as the easylang attribute does not support full HTML, such as lists and sections.

A personalization agent may replace the content with the simpler alternative, or it may put the alternative in a tooltip or help panel.

User agents may also render hard text in a different way so that users will be able to identify text that has an alternative provided.

The content must still be understandable when a user agent replaces the original content with the simpler alternative.

Supported values: String

Where easylang should use as simple well-known words as possible, and active voicing, literal text, small simple sentences. Acronyms and abbreviations should be avoided, unless they are the common way to refer to an item.

4.2.3.2 Example§

The below example section show how easylang used when coding.

Example: Easylang Using ARIA
<span aui-easylang="some text that is easy to read"> some convoluted obtuse text</span>>
4.2.3.3 Characteristics§
Characteristic Value
Related Concepts:
Used in Roles: All elements of the base markup
Inherits into Roles: Placeholder
Value: string

4.2.4 explain§

4.2.4.1 Description§

This attribute provides any information that helps the user anticipate the functionality, such as letting the user know what behavior will trigger an event. This is most important if the mechanism is not standard.

User experience: This help can be rendered as a tool tip, help link or read when the control or link is read. Most users will not want this text rendered or spoken, but other users however will need it to understand the behavior of the element.

Note that there is no default value.

These values will change when the email is sent.

4.2.4.2 Example§

The below example section show how explain used when coding.

Example: Explain Using ARIA
aui-explain="press enter to send the email" 
4.2.4.3 Characteristics§
Characteristic Value
Related Concepts:
Used in Roles: All elements of the base markup
Inherits into Roles: Placeholder
Value: string

4.2.5 feedback§

4.2.5.1 Description§

This attribute provides immediate feedback that can be shown or spoken when any event is triggered on a control.

User experience: This can be rendered as text at the top of the page and read immediately. Most users will not want this text rendered and spoken. Other users however will need it to know what has just happened.

4.2.5.2 Example§

The below example section show how feedback used when coding.

Example: Feedback Using ARIA
aui-feedback="your email on birthdays was sent" 
4.2.5.3 Characteristics§
Characteristic Value
Related Concepts:
Used in Roles: All elements of the base markup
Inherits into Roles: Placeholder
Value: string

4.2.6 moreinfo§

4.2.6.1 Description§

moreinfo provides users access to additional information about the current content in one of several formats.

A personalization agent may add additional explanatory text or provide an action for the user to take to obtain more detailed information about the content.

Supported values: URI

Note that there is no default value.

4.2.6.2 Example§

The below example section show how moreinfo used when coding.

Example: Moreinfo Using ARIA
N/A
4.2.6.3 Characteristics§
Characteristic Value
Related Concepts:
Used in Roles: All elements of the base markup
Inherits into Roles: Placeholder
Value: URI

4.2.7 extrahelp§

4.2.7.1 Description§

extrahelp provides users access to additional information about the current action or process in one or more formats.

A personalization agent may add additional explanatory text or provide an action for the user to take to obtain more detailed information or assistance in completing a task

Supported values: URI

Note that there is no default value.

4.2.7.2 Example§

The below example section show how extrahelp used when coding.

Example: Extrahelp Using ARIA
N/A
4.2.7.3 Characteristics§
Characteristic Value
Related Concepts:
Used in Roles: All elements of the base markup
Inherits into Roles: Placeholder
Value: URI

A. Vocabulary Implementations§

The vocabulary implementations of this document is available at Personalization Explainer 1.0 Vocabulary Implementations section.

B. Acknowledgments§

This section is non-normative.

The following people contributed to the development of this document.

B.1 Participants active in the Personalization TF at the time of publication§

B.2 Other Personalization TF contributors, commenters, and previously active participants§

B.3 Enabling funders§

This publication has been funded in part with U.S. Federal funds from the Health and Human Services, National Institute on Disability, Independent Living, and Rehabilitation Research (NIDILRR) under contract number HHSP23301500054C. The content of this publication does not necessarily reflect the views or policies of the U.S. Department of Health and Human Services, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government.

C. References§

C.1 Informative references§

[DOM4]
DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[SVG2]
Scalable Vector Graphics (SVG) 2. Nikos Andronikos; Rossen Atanassov; Tavmjong Bah; Amelia Bellamy-Royds; Brian Birtles; Cyril Concolato; Erik Dahlström; Chris Lilley; Cameron McCormack; Doug Schepers; Dirk Schulze; Richard Schwerdtfeger; Satoru Takagi; Jonathan Watt et al. W3C. W3C Working Draft. URL: http://www.w3.org/TR/2015/WD-SVG2-20150915/