From 86c1a71ee71dc6001cb815ba518a6ef5dc0e0187 Mon Sep 17 00:00:00 2001
From: Joshua Muheim <josh@josh.ch>
Date: Mon, 24 Sep 2018 17:15:29 +0200
Subject: [PATCH] Text changes

---
 pages/knowledge/aria/README.md                |  2 +-
 pages/knowledge/aria/bad-practices/README.md  | 10 +---
 pages/knowledge/aria/good-practices/README.md | 17 ------
 pages/knowledge/aria/purpose/README.md        | 60 +++++++++++--------
 4 files changed, 38 insertions(+), 51 deletions(-)
 delete mode 100644 pages/knowledge/aria/good-practices/README.md

diff --git a/pages/knowledge/aria/README.md b/pages/knowledge/aria/README.md
index 6d2b482d..60d58097 100644
--- a/pages/knowledge/aria/README.md
+++ b/pages/knowledge/aria/README.md
@@ -6,4 +6,4 @@ changed: "2018-05-02"
 
 # ARIA - when HTML simply is not enough
 
-**There are indeed situations where standard HTML does not provide functionalities for all the requirements developers may have for implementing modern and interactive websites. For this, the Accessible Rich Internet Applications (ARIA) technical specification was introduced. In this chapter, we introduce how it is purposely used, show its potential and shortcomings as well as alternatives to it.**
+**There are indeed situations where standard HTML does not provide functionalities for all the requirements developers may have for implementing modern and interactive websites. For this, the Accessible Rich Internet Applications (ARIA) technical specification was introduced. In this chapter, we introduce how it is purposely used, show its potential as well as its shortcomings (and alternatives, if needed).**
diff --git a/pages/knowledge/aria/bad-practices/README.md b/pages/knowledge/aria/bad-practices/README.md
index ef3ad902..b93546dc 100644
--- a/pages/knowledge/aria/bad-practices/README.md
+++ b/pages/knowledge/aria/bad-practices/README.md
@@ -6,9 +6,9 @@ changed: "2018-04-12"
 
 # Bad ARIA practices
 
-**There are certain situations where ARIA is a good (and maybe the only) way to go. But if done wrong, usage of ARIA often leads to even worse accessibility. Especially accessibility novices tend to misuse ARIA to optimise smelly code. Here we explain some of the typical dos and do nots.**
+**There are certain situations where ARIA is a good (and maybe the only) way to go. But if done wrong, usage of ARIA often leads to even worse accessibility. Especially accessibility novices tend to misuse ARIA to "optimise" smelly code.**
 
-ARIA is often misunderstood as "general repair kit" for accessibility problems. Developers new to accessibility usually think that ARIA that can be used to fix accessibility problems for all sorts of bad HTML code. In general though, throwing some ARIA attributes into the mix of bad semantics does not leverage any problem. Most of the time, the exact opposite is the case.
+ARIA is often misunderstood as "general repair kit" for accessibility problems. Developers new to accessibility usually think that ARIA can be used to fix accessibility problems for all sorts of bad HTML code. In general though, throwing some ARIA attributes into the mix of bad semantics does not leverage any problem (most of the time, the exact opposite is the case).
 
 ## Fixing broken semantics
 
@@ -150,9 +150,3 @@ So in most cases this holds true: if you face a situation where a screen reader
 Sometimes, developers try to hide focusable elements (or elements that contain focusable children) from screen readers using `aria-hidden`. This leads to unpredictable behaviour in many screen readers, as the browser still allows to focus such elements using the `Tab` key, but because of `aria-hidden` screen readers will not announce it.
 
 If you are really curious and want to learn more about this, skip ahead and read [Hiding elements from screen readers using aria-hidden](/examples/hiding-elements/from-screen-readers).
-
-The purpose of hiding something from a specific user group leads us to the next misuse of ARIA. Read on.
-
-## Conclusion: caution with ARIA!
-
-ARIA is an intriguing approach to make the web a more accessible place. In most situations though, it is neither needed (because there are usually better ways to achieve the same result) nor useful (because browser and screen reader support is still shaky).
\ No newline at end of file
diff --git a/pages/knowledge/aria/good-practices/README.md b/pages/knowledge/aria/good-practices/README.md
deleted file mode 100644
index 54c2f662..00000000
--- a/pages/knowledge/aria/good-practices/README.md
+++ /dev/null
@@ -1,17 +0,0 @@
----
-navigation_title: "Good practices"
-position: 2
-changed: "2018-05-30"
----
-
-# Good ARIA practices
-
-**There are a few ARIA features that truly fill some gaps HTML does not provide a solution for. Working pretty reliably in modern browsers and screen readers, some techniques can be recommended as safe to use.**
-
-While ARIA is not needed most of the time when developing accessible websites, it can help in certain situations to make the user experience better for screen readers.
-
-The ARIA techniques that have proven to be useful and robust will be explained in detail throughout the 4th part of this guide, [Examples of accessibility patterns](/examples), specifically in [Sensible usage of ARIA roles and attributes](/examples/sensible-aria-usage). We are carefully using ARIA here and there to optimise some of our proposed examples; this is especially true for our widgets, which are all made of traditional HTML form controls, spiced up with some JavaScript and ARIA, see [Interactive widgets](/examples/widgets).
-
-## Conclusion: be careful with ARIA!
-
-There are only rare situations where HTML is not enough. In those (and only those) situations, using ARIA is advised. In other situations, when the use of a clean and semantically correct HTML structure can provide a solution, usage of ARIA is strongly discouraged. This is due to its non-homogenous support among browsers and screen readers.
\ No newline at end of file
diff --git a/pages/knowledge/aria/purpose/README.md b/pages/knowledge/aria/purpose/README.md
index 28f97d7a..07eaa48c 100644
--- a/pages/knowledge/aria/purpose/README.md
+++ b/pages/knowledge/aria/purpose/README.md
@@ -10,7 +10,7 @@ changed: "2018-05-14"
 
 ## Handling HTML shortcomings
 
-Over the last 10 to 20 years, not much has changed to the way content is laid out and marked up in HTML. But since its early days, many de-facto standard user interface patterns have made their way into the collective awareness of the internet, often generally referred to as widgets or rich internet applications (RIAs). Many of those lack native HTML equivalents, typical examples being tablists, dropdown menus, and autocompletes.
+Over the last 10 to 20 years, not much has changed to the way content is laid out and marked up in HTML. But since its early days, many de-facto standard user interface patterns have made their way into the collective awareness of the internet, often generally referred to as widgets or rich internet applications (RIAs). Many of those lack native HTML equivalents - typical examples being tablists, dropdown menus, and autocompletes.
 
 ### Fictional tablist example
 
@@ -66,11 +66,11 @@ But simply presenting something visually is not enough for screen readers (if yo
 
 ## ARIA to the rescue (?)
 
-To fill this gap, the [Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/) - which belongs to the [World Wide Web Consortium (W3)](https://www.w3.org/) - has introduced the [ARIA](https://www.w3.org/WAI/intro/aria) technical specification. It provides specific HTML attributes (`role` and `aria-*`) that allow adding specific semantical meaning to existing HTML elements:
+To fill this gap, the [Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/) - which belongs to the [World Wide Web Consortium (W3)](https://www.w3.org/) - has introduced the technical specification [ARIA](https://www.w3.org/WAI/intro/aria). It provides specific HTML attributes (`role` and `aria-*`) that allow adding specific semantical meaning to existing HTML elements:
 
-- `role` attributes add (or override) a semantical role of an element, for example `<span role="button">`.
+- `role` adds (or overrides) a semantical role of an element, for example `<span role="button">`.
 - `aria-*` attributes provide statuses to the current semantical role, for example `<span role="button" aria-pressed="true">`.
-    - Those statuses can have specific values, depending on the role of the element.
+    - Those statuses can have specific values, depending on the role of the element. For example, `aria-pressed` can have the values `true`, `false`, and `mixed`.
 
 Many de-facto standard user interface patterns do have an ARIA specification, and so do tablists, see [Accessible Rich Internet Applications (WAI-ARIA) 1.1 - Tablist](https://www.w3.org/TR/wai-aria-1.1/#tablist).
 
@@ -95,57 +95,67 @@ Marked up with ARIA, our tablist example would look something like this:
 </div>
 ```
 
-We will take a closer look at what these attributes do (or better: what they should do) later in this chapter. For the time being, just take the following for granted.
-
 First, `role="tablist"` was added to the list container (containing the tabs). The `<ul>` element won't be announced as list now anymore by screen readers, but as something like "tablist" (depending on the screen reader).
 
-Then, `role="presentation"` was added to the list elements of the former list. As the list is not a list anymore, the specific `<li>` elements must not have specific list semantics anymore. The `presentation` role removes any semantical information: the `<li>` elements are now treated similar to plain `<div>` elements. It may seem silly to use a semantic container and then remove its semantics. But this is generally a good practice for providing backwards compatibility with legacy screen readers that may not support ARIA.
+Then, `role="presentation"` was added to the list elements of the former list. As the list is not a list anymore, the specific `<li>` elements must not have specific list semantics anymore. The `presentation` role removes any semantical information: the `<li>` elements are now treated similar to plain `<div>` elements (if you are really curious and want to learn more about this, skip ahead and read [Removing semantics using presentation role](/examples/sensible-aria-usage/presentation/)). It may seem silly to use a semantic container and then remove its semantics. But this is generally a good practice for providing backwards compatibility with legacy screen readers that may not support ARIA.
 
 Finally, `role="tab"` was added to each tab element. The `<button>` element won't be announced as button now anymore by screen readers, but as something like "tab" (depending on the screen reader). In addition, some special `aria-*` attributes were added:
 
 - `aria-controls` lets screen readers know, which tabpanel's visibility is toggled upon activation or deactivation of the tab. This allows to quickly jump from tabitem to tabpanel forth and back (depending on the screen reader).
 - `aria-selected` lets screen readers know, which tab is currently the active one, and announces this to the user with something like "active" (depending on the screen reader).
 
-Nice and clean. This looks pretty promising, does not it?
+Nice and clean. This looks pretty promising, doesn't it?
+
+### No magic all-in-one solution
 
-### A magic all-in-one solution? No.
+As HTML connaisseurs, we are used that we can add some attributes to elements, and the browser magically takes care of making it all work as expected - like providing interaction using keyboard and mouse, toggling visibility and look of elements, managing internal statuses, etc.
 
-Are you in hope of ARIA "magically" solving all the problems with missing semantics?
+ARIA is different: it is a bare set of attributes and their specific values. So in contrast to traditional HTML, the browser is not responsible of taking care of anything itself. You (the developer) have to provide it using JavaScript, CSS, and (sometimes) additional HTML!
 
-Do not be too optimistic: ARIA is a bare set of attributes and their specific values. So in contrast to traditional HTML, the browser does not take care of anything itself. You still have to provide all the interactivity yourself using JavaScript! In the current example, you need to:
+In the current example, you need to:
 
 - Implement an intuitive keyboard control pattern (or provide clear instruction of how to control the widget with keyboard only and screen readers).
 - Take care of toggling the visibility of the tabpanels.
 - Take care of toggling `aria-selected`.
 
-Admitted, a tablist is a rather easy user interface pattern, so it is not too hard to provide this functionality yourself. But there are much more complex patterns (for example, autocompletes), where it can become a major challenge managing all the required attributes and keeping their states and visual representation in sync.
+Admitted, a tablist is a rather easy user interface pattern, so it is not too hard to provide this functionality yourself. But there are much more complex patterns (for example, autocompletes), where it can become a major challenge to provide appropriate interaction, manage all the required attributes, and keeping their states and visual representation in sync.
 
-#### Varying support
+### Varying support
 
-To make things even trickier, ARIA support among browsers and screen readers varies a lot. While some may support an autocomplete or tablist pattern, others may not. And even those claiming to support a pattern are prone to being buggy. This is particularly true regarding ARIA roles: as soon as the `role` attribute is used, unexpected things may happen (if you are really curious and want to learn more about this, skip ahead and read [How screen readers work - and why they seem so buggy](/knowledge/desktop-screen-readers/so-buggy)).
+To make things even trickier, ARIA support among browsers and screen readers varies a lot. While some may support a tablist (or autocomplete) pattern, others may not.
 
-As such, there are extremely few truly working examples of ARIA widgets available on the web. And those few ones usually need a lot of complex code to work around known problems.
+Even those claiming to support a pattern are prone to being buggy. This is particularly true regarding ARIA roles: as soon as the `role` attribute is used, unexpected things may happen (if you are really curious and want to learn more about this, skip ahead and read [How screen readers work - and why they seem so buggy](/knowledge/desktop-screen-readers/so-buggy)).
 
-#### Non-homogenous behaviour
+As such, there are only few examples of ARIA widgets available on the web that truly work in all major browsers and screen readers. And those existing ones often need a lot of complex code to work around known problems.
 
-Besides bugs and many unsupported features, the ARIA specification also often is not strictly black or white, leaving it up to the manufacturers of browsers and screen readers to decide how certain functionalities should behave.
+### Non-homogenous behaviour
 
-So screen reader behaviour varies a lot regarding ARIA, especially regarding differences between browse and focus modes (if you haven't done this yet, go back and read [Screen readers' browse and focus modes](/knowledge/desktop-screen-readers/browse-focus-modes)).
+Besides bugs and unsupported features, the ARIA specification also often is not strictly black or white, leaving it up to the manufacturers of browsers and screen readers to decide how certain functionalities should behave.
 
-For example, while all screen readers announce content associated using `aria-describedby` in focus mode, some ignore it in browse mode. And while some screen readers announce the associated content right away, others leave it up to the user whether they want to hear it (by pressing a keyboard shortcut). If you are really curious and want to learn more about this, skip forward and read [Adding descriptions to elements using aria-describedby](/examples/sensible-aria-usage/describedby).
+So screen reader behaviour varies when interacting with ARIA elements, especially regarding differences between browse and focus modes (if you haven't done this yet, go back and read [Screen readers' browse and focus modes](/knowledge/desktop-screen-readers/browse-focus-modes)).
+
+For example, while all major screen readers announce content associated using `aria-describedby` in focus mode, some ignore it in browse mode. And while some screen readers announce the associated content right away, others ask the user whether they want to hear it (by pressing a keyboard shortcut). If you are really curious and want to learn more about this, skip forward and read [Adding descriptions to elements using aria-describedby](/examples/sensible-aria-usage/describedby).
 
 Another example is `aria-hidden`. Its specification promises to hide elements from screen readers. The first surprise is that `aria-hidden` simply does not work on focusable elements in most browsers. The next surprise is that `aria-hidden` does not have any effect on elements that are referenced using `aria-describedby`. If you are really curious and want to learn more about this, skip forward and read [Hiding elements from screen readers using aria-hidden](/examples/sensible-aria-usage/hidden).
 
-All this is not because of varying support degrees among modern screen readers or browsers (all of them claim to fully support `aria-describedby` and `aria-hidden`), but because of non-homogenous behaviour caused by the manufacturers' different opinions.
+All this is not because of varying support degrees among modern screen readers or browsers (all of them claim to fully support `aria-describedby` and `aria-hidden`), but because of non-homogenous behaviour caused by the manufacturers' different opinions. So which screen reader is doing it "right"? The ARIA specification does not provide an answer.
+
+And as long as no quasi-standard, no ubiquitous convention has been established, working with ARIA is often risky, potentially introducing more problems to a website's accessibility than solving them.
+
+## ARIA is good
+
+Let us make this clear: we are not against ARIA, and we certainly do not want to build up a counter-position to the standard bodies like W3C and WAI.
+
+ARIA is exactly what is needed to pave the way for modern accessibility. It often even predicts requirements that lateron are introduced into HTML, like `aria-required` resulted in the `required` attribute, or `role="dialog"` resulted in the `<dialog>` element.
 
-And as long as no quasi-standard, no ubiquitous convention has been established, working with ARIA will keep being risky.
+So ARIA is not the problem - it is the solution. But browser and screen reader vendors need to implement it uniformly, completely, and robustly. And knowing that ARIA was released in 2014, it is a real shame that this all is still in such an early stage. As developers, we can push browser and screen reader vendors by filing bugs (and inquiries) whenever we feel that something does not behave the way it is expected.
 
 ## Conclusion
 
-The intention behind ARIA is intriguing: it could be a big help in making the web a more accessible place. And knowing that ARIA was released in 2014, it is a real shame that browsers and screen readers still by far aren't capable of truly handling it in a homogenous and robust way. Alas, even if developers use ARIA in perfect accordance to its technical specification, this often will not be of much use for the targeted users. So at the time being, in most cases we do not recommend the use of ARIA. Let us hope that the situation will change for the better some time in the future.
+The intention behind ARIA is intriguing: it will be a big help in making the web an accessible place. Alas, even if developers use ARIA in perfect accordance to its technical specification, this often will not be of much use for the targeted users. So at the time being, in many cases we do not recommend the use of ARIA.
 
-Aside from the `role` attribute (which you should try to avoid in most cases), after all there exist some `aria-*` attributes that can be used standalone and are supported by all modern browsers and screen readers - more or less both homogeneously and robustly. So in some specific situations, these attributes can be of real help, but you need to know exactly in which cases. You will learn more about these in this chapter.
+But there are a few ARIA features that truly fill some gaps HTML does not provide a solution for. Working pretty reliably in modern browsers and screen readers, some of them can be recommended as safe to use.
 
-In our guide, we stick to traditional HTML solutions wherever possible to avoid shaky ARIA ground. And if we do suggest ARIA once in a while, you can be confident that it is based on years of experience, so the proposed solution is known to work and has stood the test of time.
+There exist some `aria-*` attributes that can be used standalone (without `role`) and are supported by all major browsers and screen readers - more or less homogeneously as well as robustly. So in some specific situations, these attributes can be of real help, but you need to know exactly in which cases. They will be explained in detail throughout the 4th part of this guide, [Examples of accessibility patterns](/examples), specifically in [Sensible usage of ARIA roles and attributes](/examples/sensible-aria-usage). We are carefully using ARIA here and there to optimise some of our proposed examples; this is especially true for our widgets, which are all made of traditional HTML form controls, spiced up with some JavaScript and ARIA, see [Interactive widgets](/examples/widgets).
 
-And regarding widgets: instead of using complex ARIA semantics and developing all interactivity on one's own, once again, the usage of traditional HTML helps in creating even complex interactive usage patterns. So if you haven't done this yet, go back and read [Widgets simply working for all](/knowledge/semantics/widgets).
\ No newline at end of file
+In general, in our guide, we stick to traditional HTML solutions wherever possible to avoid shaky ARIA ground. And if we do suggest ARIA once in a while, you can be confident that it is based on years of experience, so the proposed solution is known to work and has stood the test of time.