W3C

Site Navigation

Nearby

Results of Questionnaire EOWG Weekly Survey - 17 July 2015

The results of this questionnaire are available to anybody. In addition, answers are sent to the following email addresses: shawn@w3.org,shadi@w3.org,kevin@w3.org

This questionnaire was open from 2015-07-17 to 2015-07-31.

11 answers have been received.

Jump to results for question:

Tips - Writing Examples
Tips - Developing Examples

1. Tips - Writing Examples

Please review the suggested examples for the Writing Tips. Consider that for some people examples are very helpful, and for some people they may add clutter or distract from the text.

For each tip: Should we have an example for this tip or not? What do you think about the suggested example? Do you have ideas for specific example wording?

Please add your thoughts to the related GitHub issue for the tip (or, if you're not comfortable with GitHub, you can put them in the comments here).

Summary

Choice	All responders
Choice	Results
I reviewed the examples and put my comments in GitHub.	5
I reviewed the examples and put my comments below.	2
I reviewed the examples and have no comments to add	2
I have not gotten to this yet, and will do it by: [put in the Comment field the date by which you will get to it]	1
I'm not going to be able to get to this, and I will pass on commenting on it.

Details

Responder	Tips - Writing Examples	Comments
George Heake
Lydia Harkey	I reviewed the examples and have no comments to add
Kevin White	I reviewed the examples and have no comments to add	[Document author]
Brent Bakken	I reviewed the examples and put my comments below.	This is coming from someone who prefers examples... Clear and Concise: I like the example that is currently implemented. I think the audience will clearly see what you mean by complex content vs. simple content. Complex Words and Phrases: I believe tip 1 and tip 2 are separate issues and should be kept separate. Because of this, I think this tip SHOULD have an example or two that shows the focus here is on complex words and not complex writing (tip 1). I think medical, legal and/or financial jargon could be used as the example. Link Text Meaningful: I do not think an example is necessary here. The tip text has examples that area clear and understandable. Headings to Convey Meaning and Structure: If an example is needed here, maybe one like the Spacing and Headings tip from the Designing page. I am on the fence whether this needs an example or not. Editor's discretion. Unique Page Titles: I like the idea of an example of stage titles for this tip. Text Alternative for Images: Yes, include a few examples for this tip. The examples should demonstrate different reasons why the alternative text is so important. The obvious persona here is a blind user, is there another persona that can be used for a second example? Transcripts and Captions: I don't think an example is needed for this tip. Expand Acronyms: I think an example is needed. I like the current example and the tip text itself. I think they are very clearly stated.
Sharron Rush	I reviewed the examples and put my comments in GitHub.
Jonathan Metz	I reviewed the examples and put my comments in GitHub.	My comments are available here: https://github.com/w3c/wai-quick-start/pull/127#issuecomment-122241457
Shawn Lawton Henry	I reviewed the examples and put my comments in GitHub.
Vicki Menezes Miller	I reviewed the examples and put my comments in GitHub.
James Green	I reviewed the examples and put my comments below.	I support a full headings example to be crystal clear (H1,H2,H2 is enough). Quirky headings are good. If you tell a very short story or joke as your example, people may remember it better. Minor, but I found the phrase "Once we obtain information that causes us to understand the causality" distracting because it seemed unrealistic - not a real example, but like you added the phrase to make it complex on purpose. Maybe rewrite the complex side to read: "In the event of a vehicular collision, a company assigned representative will investigate to ascertain the cause and extent of damages to property belonging to the parties involved. Once cause, damages, and responsibility have been established, we will assign monetary remuneration accordingly." To think about: I know some are against the "why" but I think that without the why, some new devs and writers may just decide to skip a given tip if it's "too hard" e.g., meaningful link text - without the why, they may feel that it's too hard not to use "click here" to be worth the trouble. ... I know the why is under the "Understanding" links but newbies would not know that unless we tell them. Alt text: I think background images are worthy of a mention here, the question comes up a lot. While they are not supposed to convey information, they often are used that way (e.g., sprites). Transcripts, captions, and AD. There's a lot there, I might break it into multiple tips.
Melody Ma	I have not gotten to this yet, and will do it by: [put in the Comment field the date by which you will get to it]	End of this week
Andrew Arch	I reviewed the examples and put my comments in GitHub.

2. Tips - Developing Examples

Please review the suggested examples for the Developing Tips. Consider that for some people examples are very helpful, and for some people they may add clutter or distract from the text.

For each tip: Should we have an example for this tip or not? What do you think about the suggested example? Do you have ideas for specific example wording?

Please add your thoughts to the related GitHub issue for the tip (or, if you're not comfortable with GitHub, you can put them in the comments here).

Summary

Choice	All responders
Choice	Results
I reviewed the examples and put my comments in GitHub.	5
I reviewed the examples and put my comments below.	3
I reviewed the examples and have no comments to add	2
I have not gotten to this yet, and will do it by: [put in the Comment field the date by which you will get to it]	1
I'm not going to be able to get to this, and I will pass on commenting on it.

Details

Responder	Tips - Developing Examples	Comments
George Heake	I reviewed the examples and put my comments below.	Good simple and concise examples to demonstrate best practices regarding accessible developing practices.
Lydia Harkey	I reviewed the examples and have no comments to add
Kevin White	I reviewed the examples and have no comments to add	[Document author]
Brent Bakken	I reviewed the examples and put my comments below.	This is coming from someone who prefers examples, AND has no experience as a developer... Progressing Enhancement: No example needed for this tip. Responsive Design: I think an example here would be good. Something that shows how very different content will look on various viewports if designed responsively. This may be one where you could show a bad example of usability on a small viewport if responsive design is not implemented (or implemented poorly). Mark-up to Convey Meaning or Structure: Because of my lack of knowledge, I am not sure whether this tip needs and example or not. An example would probably help me understand the tip more, but that is probably because I am not a developer. Whatever EO collectively decides is fine with me. Associate Forms/Labels: I think a code snippet example would be good here. A visual could be added as well if it is helpful and appropriately matching the snippet. Avoid and Correct Mistakes: I think there should be an example here. Since the Designing page has an example showing what the mistake is and what should be corrected, I think this example should focus on the "avoidance" of the mistake. The first example is good (password or date), I cannot tell you how many times I have lost data in forms when filling out a multi form page simply because my password did not conform to the requirements, and the requirements were not clearly given in the first place. Frustrating. Reading/Code Order: I like the suggested example for this tip. Provide Meaning to Non-standard Interactive Elements: Again, because of my lack of knowledge, I am not sure whether this tip needs and example or not. An example would probably help me understand the tip more, but that is probably because I am not a developer. Whatever EO collectively decides is fine with me. Keyboard Accessible: I don't feel an example is needed for this tip. Code Validates: I don't feel strongly that an example is needed, but maybe you could show some invalid code that works fine on a desktop or laptop with a basic screen reader, but when a specific AT is introduced, such as a refreshable Braille display, the code is not sufficient and can introduce access barriers. Just an idea of trying to show how code may be good enough to "work" but if it is not valid it may not "work" in all situations vs. code that was validated. This idea may be to complex.
Sharron Rush	I reviewed the examples and put my comments in GitHub.
Jonathan Metz	I reviewed the examples and put my comments in GitHub.	https://github.com/w3c/wai-quick-start/pull/160
Shawn Lawton Henry	I reviewed the examples and put my comments in GitHub.
Vicki Menezes Miller	I reviewed the examples and put my comments in GitHub.
James Green	I reviewed the examples and put my comments below.	Responsive. I see much value in an example in a new window that they can resize. Markup to convey... I think we need a few examples here - it's a good general tip, but without a starting point of several solid examples, the tip means little. Labels - perhaps show the offscreen label example too. Why not discuss aria labels? Code order - I think the example can be enhanced if we craft the visual design in a way that places main content elements next to each other, maybe with contextual information alongside it so it would be hard to get a consensus on the natural code order were you not to evaluate the content. This will highlight the value of natural code order. E.g., something to buy: image on left, buy button and price below it, title on right, detailed description below that. I would argue (following the "Front-load important messages" tip from writing) that the correct order is 1. title 2. image (with good alt) 3. description, 4. buy button. non-standard elements - lots here, should we define the few most common and show aria for them? this, like markup to convey meaning, is not much of a tip without examples... keyboard - I'd change "such as menus, collapsable accordions, or media players." to "such as menus, mouse-over info, collapsable accordions, or media players." Maybe an example showing the use of keyboard events along with mouse events vs. a bad one that only uses mouse events. alt - i think discussing background images is even more important here. language -a good example for "language of phrases" would be a language selector input that lists the languages in their native tongue.
Melody Ma	I have not gotten to this yet, and will do it by: [put in the Comment field the date by which you will get to it]	End of this week
Andrew Arch	I reviewed the examples and put my comments in GitHub.	29 July at latest - sorry this didn't happen until 31/7 Initial comment - code examples for many of the tips are going to take too much space :( maybe we need more tutorials :)