This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.

Bug 21102 - proofreading / typos
Summary: proofreading / typos
Status: RESOLVED FIXED
Alias: None
Product: HTML WG
Classification: Unclassified
Component: Using ARIA in HTML (show other bugs)
Version: unspecified
Hardware: PC Linux
: P3 minor
Target Milestone: ---
Assignee: dmacdona
QA Contact: This bug has no owner yet - up for the taking
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2013-02-24 17:50 UTC by yago dlt
Modified: 2014-01-18 13:46 UTC (History)
3 users (show)

See Also:


Attachments

Description yago dlt 2013-02-24 17:50:39 UTC
The following are just proofreading recommendations for enhanced readability. They are by no means bugs and should not be treated as such.

Recommendation 1:
The second paragraph of section '1.Introduction' reads:
"This document suggests which ARIA attributes it is appropriate to use..."

For grammatical coherence it should read:
"This document suggests which ARIA attributes *are* appropriate to use..."

Recommendation 2:
The third paragraph of section '1.Introduction' reads:
"For general best-practice information for using ARIA, see the..."

It would be more appropriate if it read:
"For general best-practice information *about* using ARIA, see the..."

Recommendation 3:
The second paragraph of section '2.3 Third rule of ARIA use' reads:
"If you create a widget that a user can click or tap or drag or drop or slide or scroll a user must also be able navigate to the widget and perform an equivalent action using the keyboard."

My recommendation here is that it read:
"If you create a widget that a user can click or tap or drag or drop or slide or scroll*,* a user must also be able *to* navigate to the widget and perform an equivalent action using the keyboard.

Recommendation 4:
The second <h3> of the section '2.4 What does adding a role do to the native semantics?' reads:
"What adding a role does not do?"

Expressing this as a question obscures the simplicity of what the spec intends to say, making it less understandable for people who's English skills are not that great, so my recommendation is that it merely say: "What adding a role does not do", without the question mark.

Recommendation 5:
The penultimate paragraph of the above section reads:
"But it can still be pressed, it is still in the default tab order, still looks like a button, still triggers any associated actions when pressed."

Grammatically this is not wrong, but it leaves the reader with a taste that he/she is missing something, as if the information was not complete, and they may want to re-read the phrase to make sure he/she hasn't missed something. Therefore I would recommend that it read:
"But it can still be pressed, it is still in the default tab order, still looks like a button *and* still triggers any associated actions when pressed."

Recommendation 6:
The second half of the first paragraph of the section '2.5 Add ARIA inline or via script?' reads:
"If the content and interaction is only supported in a scripting enabled browsing context, for example Google docs applications require JavaScript enabled to work, so it is safe for them to include the ARIA markup inline."

Here there are two issues: the first one is that 'scripting enabled' should be hyphenated as they form one compound adjective, and the second one is that the whole phrase doesn't make a lot of sense the way it stands. My recommendation is that it read:
"If the content and interaction is only supported in a scripting-enabled browsing context, i.e. Google Docs (its applications require JavaScript enabled to work), it is safe to include the ARIA markup inline."

Recommendation 7:
The last phrase of the first paragraph on the '2.6 ARIA validation' section reads:
"[...] but validation tools will produce errors when they encounter ARIA markup as the associated DTDs have not been updated to recognise ARIA markup and it is unlikely they ever will be."

This assumes that none of the DTDs associated to any validators are up to date, which might be perfectly true (I don't claim to know anything about validators), but I find it rather assuming to express it in this manner. My recommendation for this would be: 
"[...]but validation tools will produce errors when they encounter ARIA markup *if* the associated DTDs have not been updated to recognise *them*, which, unfortunately, is the most likely case scenario and likely to remain so.

Recommendation 8:
The first paragraph on the section '2.8 aria-labelledby and aria-describedby' reads:
"Currently aria-labelledby and aria-describedby are more robustly supported for associating text content to a subset of interactive content elements, they do not work correctly on links, support on embedded content is unknown, but can be safely used on form controls including the many input types."

This paragraph also makes arguable sense from a grammatical point of view. My recommendation is that it read:
"Currently aria-labelledby and aria-describedby are more robustly supported for associating text content to a subset of interactive content elements*. They* do not work correctly on links *and their* support on embedded content is unknown, but *they* can be safely used on form controls including the many input types.


Recommendation 9:
The end of the second <p> under the section '2.9 Using ARIA role=application' reads as follows:
"Screen readers and other assistive technologies that support WAI-ARIA will support switching between browse and focus modes for these by default, too:"

In here the comma just before too is incorrect. Therefore, it should read:
"Screen readers and other assistive technologies that support WAI-ARIA will support switching between browse and focus modes for these by default too:"

Recommendation 10:
Within the same section, the third <li> of the second <ul> should have a comma right before 'etc', so it should read:
"table that has focusable items and is being navigated via the arrow keys, for example a list of e-mail messages where you provide specific information. Other examples are interactive grids, tree grids*,* etc.

Recommendation 11:
In the same <ul>, the fifth <li> reads:
"[...]These cause screen readers to go into a sort of application mode implicitly once focus moves to a control inside them."

This is a pretty weird use of the adverb implicitly, in its stead, I would write: 
"[...]These cause screen readers to go into a sort of *implicit* application mode once focus moves to a control inside them."

Recommendation 12:
Still within the '2.9 Using ARIA role=application', its third <p> reads:
"You only want to use role=application if the content you’re providing consists of only interactive controls, and of those, mostly advanced widgets, that emulate a real desktop application[...]"

Here we have an extra comma, just before 'that', that should not be there:
"You only want to use role=application if the content you’re providing consists of only interactive controls, and of those, mostly advanced widgets that emulate a real desktop application[...]"

Recommendation 13:
In that very same paragraph, the text continues:
"[...]be it FaceBook posts and comments, blogs, Twitter feeds, even accordions that show and hide certain types of information dynamically."

There are two problems here: the first one is that 'FaceBook' should be written 'Facebook' (not that I care very much for them, but it's their branding and we cannot mess with that); the second one is, again, punctuation. The last comma should have been an 'or' or an 'and' to make the list grammatically correct, or there should have been an ellipsis after the word 'feeds':

a) "[...]be it FaceBook posts and comments, blogs, Twitter feeds or even accordions that show and hide certain types of information dynamically. "

b) "[...]be it FaceBook posts and comments, blogs, Twitter feeds..., even accordions that show and hide certain types of information dynamically. "

Recommendation 14:
Still in this section, the fourth <p> reads:
"In short: The times when you actually will use role=application is probably going to be in very rare cases!"
which is a bit of a grammatical incoherence.

Instead, it should read something along the lines of:
"In short: The times when you actually will use role=application are going to be very rare!"

Recommendation 15:
The first <p> after the <h3>So where do I put role=application in the rare cases it is useful?<h3> reads:
"[...]for example the parent div of your element that is your outer most widget element.[...]"

The problem here is that 'outer most' is one word. Therefore:
"[...]for example the parent div of your element that is your *outermost* widget element.[...]" should be written instead.

Recommendation 16:
At the beginning of the section '2.10 Recommendations Table:', the first <li> finishes like so:
"There are notes indicating under certain circumstances default semantics are useful."

I'm pretty sure what the spec meant in this point is that:
"There are notes indicating under *which* circumstances default semantics are useful."

N.B.: on the next <li>, the N/A one, the anchor leaves the 'I' of 'API' behind.

Recommendation 17:
Just a little bit further, the text goes on to say:
"NONE = the element does not support ARIA roles, states and properties, this is usually because the element is not displayed in the document."

Again, punctuation. Before 'this' there should have been a full stop:
"NONE = the element does not support ARIA roles, states and properties*. This* is usually because the element is not displayed in the document."



Unfortunately, I don't have any more time to spare today. I'm sure there would be a few more recommendations I could give, but I hope these 17 [...] are enough for the time being and show the need for proofreading before the text leaves the draft state.

All the best!

@yagohimself
Comment 1 dmacdona 2014-01-15 00:08:37 UTC
The following are just proofreading recommendations for enhanced readability. They are by no means bugs and should not be treated as such.

Recommendation 1:
The second paragraph of section '1.Introduction' reads:
"This document suggests which ARIA attributes it is appropriate to use..."

For grammatical coherence it should read:
"This document suggests which ARIA attributes *are* appropriate to use..."
DONE
=======
Recommendation 2:
The third paragraph of section '1.Introduction' reads:
"For general best-practice information for using ARIA, see the..."

It would be more appropriate if it read:
"For general best-practice information *about* using ARIA, see the..."
DONE
======
Recommendation 3:
The second paragraph of section '2.3 Third rule of ARIA use' reads:
"If you create a widget that a user can click or tap or drag or drop or slide or scroll a user must also be able navigate to the widget and perform an equivalent action using the keyboard."

My recommendation here is that it read:
"If you create a widget that a user can click or tap or drag or drop or slide or scroll*,* a user must also be able *to* navigate to the widget and perform an equivalent action using the keyboard.

DONE

=======
Recommendation 4:
The second <h3> of the section '2.4 What does adding a role do to the native semantics?' reads:
"What adding a role does not do?"

Expressing this as a question obscures the simplicity of what the spec intends to say, making it less understandable for people who's English skills are not that great, so my recommendation is that it merely say: "What adding a role does not do", without the question mark.
DONE
=========
Recommendation 5:
The penultimate paragraph of the above section reads:
"But it can still be pressed, it is still in the default tab order, still looks like a button, still triggers any associated actions when pressed."

Grammatically this is not wrong, but it leaves the reader with a taste that he/she is missing something, as if the information was not complete, and they may want to re-read the phrase to make sure he/she hasn't missed something. Therefore I would recommend that it read:
"But it can still be pressed, it is still in the default tab order, still looks like a button *and* still triggers any associated actions when pressed."
DONE
========
Recommendation 6:
The second half of the first paragraph of the section '2.5 Add ARIA inline or via script?' reads:
"If the content and interaction is only supported in a scripting enabled browsing context, for example Google docs applications require JavaScript enabled to work, so it is safe for them to include the ARIA markup inline."

Here there are two issues: the first one is that 'scripting enabled' should be hyphenated as they form one compound adjective, and the second one is that the whole phrase doesn't make a lot of sense the way it stands. My recommendation is that it read:
"If the content and interaction is only supported in a scripting-enabled browsing context, i.e. Google Docs (its applications require JavaScript enabled to work), it is safe to include the ARIA markup inline."

DONE combined with prior bug filed on this paragraph by another
========
Recommendation 7:
The last phrase of the first paragraph on the '2.6 ARIA validation' section reads:
"[...] but validation tools will produce errors when they encounter ARIA markup as the associated DTDs have not been updated to recognise ARIA markup and it is unlikely they ever will be."

This assumes that none of the DTDs associated to any validators are up to date, which might be perfectly true (I don't claim to know anything about validators), but I find it rather assuming to express it in this manner. My recommendation for this would be: 
"[...]but validation tools will produce errors when they encounter ARIA markup *if* the associated DTDs have not been updated to recognise *them*, which, unfortunately, is the most likely case scenario and likely to remain so.

WONTFIX the paragraph is accurate... only html5 validators will not throw errors.

=========
Recommendation 8:
The first paragraph on the section '2.8 aria-labelledby and aria-describedby' reads:
"Currently aria-labelledby and aria-describedby are more robustly supported for associating text content to a subset of interactive content elements, they do not work correctly on links, support on embedded content is unknown, but can be safely used on form controls including the many input types."

This paragraph also makes arguable sense from a grammatical point of view. My recommendation is that it read:
"Currently aria-labelledby and aria-describedby are more robustly supported for associating text content to a subset of interactive content elements*. They* do not work correctly on links *and their* support on embedded content is unknown, but *they* can be safely used on form controls including the many input types.

Previously FIXED
===========
Recommendation 9:
The end of the second <p> under the section '2.9 Using ARIA role=application' reads as follows:
"Screen readers and other assistive technologies that support WAI-ARIA will support switching between browse and focus modes for these by default, too:"

In here the comma just before too is incorrect. Therefore, it should read:
"Screen readers and other assistive technologies that support WAI-ARIA will support switching between browse and focus modes for these by default too:"

DONE
==========
Recommendation 10:
Within the same section, the third <li> of the second <ul> should have a comma right before 'etc', so it should read:
"table that has focusable items and is being navigated via the arrow keys, for example a list of e-mail messages where you provide specific information. Other examples are interactive grids, tree grids*,* etc.

DONE
===========
Recommendation 11:
In the same <ul>, the fifth <li> reads:
"[...]These cause screen readers to go into a sort of application mode implicitly once focus moves to a control inside them."

This is a pretty weird use of the adverb implicitly, in its stead, I would write: 
"[...]These cause screen readers to go into a sort of *implicit* application mode once focus moves to a control inside them."

WONT FIX... a little weird yes, but it is describing a "sort of" behaviour  ...but put brackets around implicitly.

===========
Recommendation 12:
Still within the '2.9 Using ARIA role=application', its third <p> reads:
"You only want to use role=application if the content you’re providing consists of only interactive controls, and of those, mostly advanced widgets, that emulate a real desktop application[...]"

Here we have an extra comma, just before 'that', that should not be there:
"You only want to use role=application if the content you’re providing consists of only interactive controls, and of those, mostly advanced widgets that emulate a real desktop application[...]"

DONE
=======
Recommendation 13:
In that very same paragraph, the text continues:
"[...]be it FaceBook posts and comments, blogs, Twitter feeds, even accordions that show and hide certain types of information dynamically."

There are two problems here: the first one is that 'FaceBook' should be written 'Facebook' (not that I care very much for them, but it's their branding and we cannot mess with that); the second one is, again, punctuation. The last comma should have been an 'or' or an 'and' to make the list grammatically correct, or there should have been an ellipsis after the word 'feeds':

a) "[...]be it FaceBook posts and comments, blogs, Twitter feeds or even accordions that show and hide certain types of information dynamically. "

b) "[...]be it FaceBook posts and comments, blogs, Twitter feeds..., even accordions that show and hide certain types of information dynamically. "

DONE
======
Recommendation 14:
Still in this section, the fourth <p> reads:
"In short: The times when you actually will use role=application is probably going to be in very rare cases!"
which is a bit of a grammatical incoherence.

Instead, it should read something along the lines of:
"In short: The times when you actually will use role=application are going to be very rare!"

DONE
========
Recommendation 15:
The first <p> after the <h3>So where do I put role=application in the rare cases it is useful?<h3> reads:
"[...]for example the parent div of your element that is your outer most widget element.[...]"

The problem here is that 'outer most' is one word. Therefore:
"[...]for example the parent div of your element that is your *outermost* widget element.[...]" should be written instead.

DONE
=======
Recommendation 16:
At the beginning of the section '2.10 Recommendations Table:', the first <li> finishes like so:
"There are notes indicating under certain circumstances default semantics are useful."

I'm pretty sure what the spec meant in this point is that:
"There are notes indicating under *which* circumstances default semantics are useful."

N.B.: on the next <li>, the N/A one, the anchor leaves the 'I' of 'API' behind.

DONE
=======
Recommendation 17:
Just a little bit further, the text goes on to say:
"NONE = the element does not support ARIA roles, states and properties, this is usually because the element is not displayed in the document."

Again, punctuation. Before 'this' there should have been a full stop:
"NONE = the element does not support ARIA roles, states and properties*. This* is usually because the element is not displayed in the document."
DONE
Comment 2 dmacdona 2014-01-17 13:22:26 UTC
This can now be closed