About Page: Revise intro to better describe WAI-APG site #2313

mcking65 · 2022-05-09T00:21:35Z

This PR rewrite the introduction section so its content is more appropriate for the about page of the new WAI APG site. It describes the purpose of the APG and its structure for someone who is new to APG. It also explains the purpose of ARIA and sets in the broader context of WAI work.

This revision assumes that the "Fundamentals" page is renamed to "Practices" as requested in w3c/wai-aria-practices#60 and that the "About" page is revised as described in w3c/wai-aria-practices#66.

Preview

The new content can be viewed in context under the "Introduction" heading on the about page in netlify.

WAI Preview Link

💥 Error: 504 Gateway Timeout 💥

PR Preview failed to build. (Last tried on May 10, 2022, 1:22 AM UTC).

More

PR Preview relies on a number of web services to run. There seems to be an issue with the following one:

🚨 Spec Generator - Spec Generator is the web service used to build specs that rely on ReSpec.

🔗 Related URL

<html><body><h1>504 Gateway Time-out</h1>
The server didn't respond in time.
</body></html>

If you don't have enough information above to solve the error by yourself (or to understand to which web service the error is related to, if any), please file an issue.

charmarkk

Offered a few pieces of feedback to consider! I don't know if I did something wrong, but I could only leave comments on lines of code. I remember there is/was a way to suggest a change so it's as easy as clicking a button to make that change, but I'm not sure if Github removed that, if I forgot how to do it, or if it's not doable on this particular item.

charmarkk · 2022-05-09T16:57:25Z

aria-practices.html

    </p>
    <p>
-      Languages used to create rich and dynamic web sites, e.g., HTML, JavaScript, CSS, and SVG, do not natively include all the features required to make sites usable by people who use assistive technologies (AT) or who rely on keyboard navigation.
+      Accessibility semantics are the meaning of user interface elements that need to be conveyed to assistive technology users in order for those users to understand and use the elements.


Change "Accessibility semantics are" to "Accessibility semantics refers to"

charmarkk · 2022-05-09T16:58:54Z

aria-practices.html

-      Languages used to create rich and dynamic web sites, e.g., HTML, JavaScript, CSS, and SVG, do not natively include all the features required to make sites usable by people who use assistive technologies (AT) or who rely on keyboard navigation.
+      Accessibility semantics are the meaning of user interface elements that need to be conveyed to assistive technology users in order for those users to understand and use the elements.
+      For example, people who can visually perceive a search icon button understand the element can be activated to perform a search by the way it is styled and positioned.
+      To make that icon accessible to a screen reader user, one of the semantics that needs to be communicated is that the element represents a button, and there are several ways that semantic can be conveyed to assistive technologies in code.


Change "that semantic can" to "that semantic meanings can"

Actually, your suggestion prompted to reconsider that sentence; I deleted the entire phrase after "and" ... it is not necessary to land the points of the paragraph.

charmarkk · 2022-05-09T17:00:20Z

aria-practices.html

+      Accessibility semantics are the meaning of user interface elements that need to be conveyed to assistive technology users in order for those users to understand and use the elements.
+      For example, people who can visually perceive a search icon button understand the element can be activated to perform a search by the way it is styled and positioned.
+      To make that icon accessible to a screen reader user, one of the semantics that needs to be communicated is that the element represents a button, and there are several ways that semantic can be conveyed to assistive technologies in code.
+      In addition, for the button to be accessible via a keyboard, it needs to be keyboard focusable, and it is commonly expected that when focused, pressing <kbd>Enter</kbd> or <kbd>Space</kbd> will activate it.


Change "for the button to be accessible via a keyboard, it needs to be keyboard focusable," to "for the button to be accessible via keyboard it needs to be keyboard focusable," (removed comma after keyboard and "a" before "keyboard")

I simplified the sentence to be:

In addition, keyboard accessibility requires the button to be focusable, and keyboard conventions call for pressing Enter or Space to activate the button when it is focused.

charmarkk · 2022-05-09T17:02:25Z

aria-practices.html

+      The APG is organized into two major sections: patterns and practices.
+      Each pattern explains how to make a common user interface element, such as a button, menu, or dialog, accessible, and provides functional example implementations of the pattern.
+      The practices section gives in-depth explanation of how to satisfy a variety of accessibility needs that surface when making rich internet application experiences accessible.
+      For instance, the practices section on providing accessible names and descriptions gives detailed description of seven different naming techniques as well as a table providing guidance for naming more than 80 types of elements.


Change "gives detailed description" to "gives a detailed description"

Instead made description plural since there are 7

charmarkk · 2022-05-09T17:03:49Z

aria-practices.html

+    <p>
+      The APG assumes basic understanding of web development, especially of HTML and CSS.
+      It may be particularly useful to designers and engineers who are working on site design systems and component libraries.
+      However, it is important to understand that the APG covers only a portion of what is needed to create accessible experiences.


Swap "APG covers only a portion" to "APG only covers a portion" (reads with a little more emphasis, imo)

charmarkk · 2022-05-09T17:04:49Z

aria-practices.html

+    <p>
+      The accessibility semantics used in the APG patterns and described in APG practices are defined in the
+      <cite><a href="https://www.w3.org/TR/wai-aria-1.2/">WAI-ARIA 1.2 Specification</a></cite>.
+      That is, the ARIA specification standardizes the meaning of the attributes that describe elements and their states to assistive technologies, e.g., the meaning of <code>role="button"</code>.


Change "e.g., the..." to "such as the" (less punctuation clutter, since there's lots of commas around there already)

charmarkk · 2022-05-09T17:05:33Z

aria-practices.html

+      The accessibility semantics used in the APG patterns and described in APG practices are defined in the
+      <cite><a href="https://www.w3.org/TR/wai-aria-1.2/">WAI-ARIA 1.2 Specification</a></cite>.
+      That is, the ARIA specification standardizes the meaning of the attributes that describe elements and their states to assistive technologies, e.g., the meaning of <code>role="button"</code>.
+      These attributes and other features required to make sites usable by people who rely on assistive technologies or keyboard navigation are not natively included in the languages used to create web sites, e.g., HTML, JavaScript, CSS, and SVG.


Change "e.g., HTML," to "such as HTML, ..." (ibid.)

a11ydoer · 2022-05-09T17:20:25Z

@mcking65

The contents are excellent and cover all the aspects of APG. I liked that you emphasized two major sections, pattern, and practices.

"about" page includes

What ARIA APG is
What Accessibility semantics are and how APG is used for that
Two major sections of APG: Pattern and Practice
The Coverage of APG and further resources beyond APG
Relationship with ARIA

Minor suggestions if we have time

link to [patterns] can be added to about page content
Each sentence is a bit long with multiple coordinating conjunctions such as "and" (Cognitive load to read through the sentences)
whether new users will understand the concept of "rich internet applications"
The order of sentences in the last paragraph - The last two sentences can be the beginning of the last paragraph. ( I will mark the suggested change in the file)

charmarkk · 2022-05-09T18:27:35Z

Those are good points too @a11ydoer. I can take a stab at wordsmithing if you want, @mcking65.

mcking65 · 2022-05-09T18:46:22Z

I will incorporate this feedback this afternoon, many thanks @charmarkk and @a11ydoer!!

I think it is helpful to use the term "rich internet applications" strategically in a few places because that is what the RIA stands for in "ARIA". I think it is important for people to make the connection.

a11ydoer · 2022-05-09T19:28:19Z

@mcking65

We don't need to resolve this. Even this is not the scope of the work here.

My question is more about "rich" concept to new comers when we use the word, "rich internet applications" (I am not sure whether the "rich" came from the name, Rich Schwerdtfeger. :) )

My understanding is that the word, "rich" is used to present the technology such as javascript, which did not exist before to create composite and complex web widgets. I may be wrong. I am tagging @jnurthen out of curiosity.

mcking65 · 2022-05-09T19:49:38Z

@a11ydoer wrote:

My question is more about "rich" concept to new comers when we use the word, "rich internet applications" (I am not sure whether the "rich" came from the name, Rich Schwerdtfeger. :) )

LOL!!!

My understanding is that the word, "rich" is used to present the technology such as javascript, which did not exist before to create composite and complex web widgets.

Exactly, rich refers to user interfaces that are dynamic, interactive, graphical, or visually complex in nature.

a11ydoer · 2022-05-09T21:47:03Z

Exactly, rich refers to user interfaces that are dynamic, interactive, graphical, or visually complex in nature.

It would be great if we can indicate the concept/definition of "rich" somewhere in the doc.

a11ydoer

I already added my feedback above. It looks good to me. I would not worry to swap the order of two sentences in the last phragraph for now. Thanks for great job, @mcking65

a11ydoer · 2022-05-09T22:01:37Z

Offered a few pieces of feedback to consider! I don't know if I did something wrong, but I could only leave comments on lines of code. I remember there is/was a way to suggest a change so it's as easy as clicking a button to make that change, but I'm not sure if Github removed that, if I forgot how to do it, or if it's not doable on this particular item.

@charmarkk I think you are referring to the function under "file changed", "edit file" (three dots next to "viewed"), and then "creating a new branch for this commit and start a pull request" However, I am not sure whether this issue has the connected pipeline to new site PR and repo.

charmarkk · 2022-05-09T23:58:03Z

Offered a few pieces of feedback to consider! I don't know if I did something wrong, but I could only leave comments on lines of code. I remember there is/was a way to suggest a change so it's as easy as clicking a button to make that change, but I'm not sure if Github removed that, if I forgot how to do it, or if it's not doable on this particular item.

@charmarkk I think you are referring to the function under "file changed", "edit file" (three dots next to "viewed"), and then "creating a new branch for this commit and start a pull request" However, I am not sure whether this issue has the connected pipeline to new site PR and repo.

OHH I think it might be because this is a PR, not an issue fix. I think the suggest feature I'm thinking of only applies to issue commits. (Or maybe I've totally lost it and they did remove it!) Either way, I bet you're right, it might not be connected up in the way it'd need to be to make a PR for the PR. @mcking65 Let me know if there's anything I can do to make things more readable! Great work.

mcking65 · 2022-05-10T01:29:32Z

Offered a few pieces of feedback to consider! I don't know if I did something wrong, but I could only leave comments on lines of code. I remember there is/was a way to suggest a change so it's as easy as clicking a button to make that change, but I'm not sure if Github removed that, if I forgot how to do it, or if it's not doable on this particular item.

@charmarkk I think you are referring to the function under "file changed", "edit file" (three dots next to "viewed"), and then "creating a new branch for this commit and start a pull request" However, I am not sure whether this issue has the connected pipeline to new site PR and repo.

OHH I think it might be because this is a PR, not an issue fix. I think the suggest feature I'm thinking of only applies to issue commits. (Or maybe I've totally lost it and they did remove it!) Either way, I bet you're right, it might not be connected up in the way it'd need to be to make a PR for the PR.

Nop, awesome, review thanks.

What you want is there. If you have a simple suggestion, pls don't make a pr against a pr! After pressing the add comment button for a line, there is a button in the composer toolbar named "suggestion". Or, you can just press ctrl+g (windows). It adds the markdown for a suggestion into the composer, and you can just edit the text it puts in the box.

Revise intro to better describe WAI-APG site

90efc67

mcking65 changed the title ~~Revise intro to better describe WAI-APG site~~ About Page: Revise intro to better describe WAI-APG site May 9, 2022

fix spelling

9d18d81

mcking65 requested review from a11ydoer and charmarkk May 9, 2022 00:46

charmarkk requested changes May 9, 2022

View reviewed changes

a11ydoer approved these changes May 9, 2022

View reviewed changes

Incorporate feedback from Mark

62965c3

mcking65 merged commit e2c8b04 into main May 10, 2022

mcking65 deleted the about-intro branch May 10, 2022 01:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

About Page: Revise intro to better describe WAI-APG site #2313

About Page: Revise intro to better describe WAI-APG site #2313

mcking65 commented May 9, 2022 •

edited by pr-preview bot

Loading

charmarkk left a comment

charmarkk May 9, 2022

charmarkk May 9, 2022

mcking65 May 10, 2022

charmarkk May 9, 2022 •

edited

Loading

mcking65 May 10, 2022

charmarkk May 9, 2022 •

edited

Loading

mcking65 May 10, 2022

charmarkk May 9, 2022 •

edited

Loading

charmarkk May 9, 2022 •

edited

Loading

charmarkk May 9, 2022 •

edited

Loading

a11ydoer commented May 9, 2022 •

edited

Loading

charmarkk commented May 9, 2022

mcking65 commented May 9, 2022

a11ydoer commented May 9, 2022

mcking65 commented May 9, 2022

a11ydoer commented May 9, 2022

a11ydoer left a comment

a11ydoer commented May 9, 2022

charmarkk commented May 9, 2022

mcking65 commented May 10, 2022

About Page: Revise intro to better describe WAI-APG site #2313

About Page: Revise intro to better describe WAI-APG site #2313

Conversation

mcking65 commented May 9, 2022 • edited by pr-preview bot Loading

Preview

💥 Error: 504 Gateway Timeout 💥

charmarkk left a comment

Choose a reason for hiding this comment

charmarkk May 9, 2022

Choose a reason for hiding this comment

charmarkk May 9, 2022

Choose a reason for hiding this comment

mcking65 May 10, 2022

Choose a reason for hiding this comment

charmarkk May 9, 2022 • edited Loading

Choose a reason for hiding this comment

mcking65 May 10, 2022

Choose a reason for hiding this comment

charmarkk May 9, 2022 • edited Loading

Choose a reason for hiding this comment

mcking65 May 10, 2022

Choose a reason for hiding this comment

charmarkk May 9, 2022 • edited Loading

Choose a reason for hiding this comment

charmarkk May 9, 2022 • edited Loading

Choose a reason for hiding this comment

charmarkk May 9, 2022 • edited Loading

Choose a reason for hiding this comment

a11ydoer commented May 9, 2022 • edited Loading

charmarkk commented May 9, 2022

mcking65 commented May 9, 2022

a11ydoer commented May 9, 2022

mcking65 commented May 9, 2022

a11ydoer commented May 9, 2022

a11ydoer left a comment

Choose a reason for hiding this comment

a11ydoer commented May 9, 2022

charmarkk commented May 9, 2022

mcking65 commented May 10, 2022

mcking65 commented May 9, 2022 •

edited by pr-preview bot

Loading

charmarkk May 9, 2022 •

edited

Loading

charmarkk May 9, 2022 •

edited

Loading

charmarkk May 9, 2022 •

edited

Loading

charmarkk May 9, 2022 •

edited

Loading

charmarkk May 9, 2022 •

edited

Loading

a11ydoer commented May 9, 2022 •

edited

Loading