[Bug 21102] New: proofreading / typos

https://www.w3.org/Bugs/Public/show_bug.cgi?id=21102

            Bug ID: 21102
           Summary: proofreading / typos
    Classification: Unclassified
           Product: HTML WG
           Version: unspecified
          Hardware: PC
                OS: Linux
            Status: NEW
          Severity: trivial
          Priority: P3
         Component: Using ARIA in HTML
          Assignee: faulkner.steve@gmail.com
          Reporter: yagonuchera@hotmail.com
        QA Contact: dave.null@w3.org
                CC: mike@w3.org, public-html-bugzilla@w3.org

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

-- 
You are receiving this mail because:
You are on the CC list for the bug.

Received on Sunday, 24 February 2013 17:50:40 UTC