Improve Accessibility Guidance for describe() Usage
#8101
Conversation
….js; simple docs are updated, not code
|
Hi @NalinDalal , thanks for preparing this. I left some comments, but most notably, I see that this PR has combined your work on the text-related reference which is a separate issue. Please isolate your PR to only contain what's related to the linked issue before implementing the suggestions. One way to isolate the PR would be to:
Then you can push and open a PR from that new branch, and work on it from there. In general / in the future, I would recommend working on separate branches for each issue in your fork, to avoid these collisions. (If you know other ways to clean up this PR so it focuses only on the linked issue, please feel free to do that, the above is just the most straightforward steps I typically recommend in this kind of situation - so I hope it helps, please let me know if you have questions.) Lastly, you wrote:
Please either include this in the PR (it's still directly related to the issue) or change the link from "Resolves #6387" to "Addresses #6387" to avoid autoclosing. Totally up to you, either is alright! |
|
|
||
| # Canvas Accessibility Descriptions: `describe()` | ||
|
|
||
| To make p5.js sketches accessible, every example that draws to the canvas should include a call to [`describe()`](https://p5js.org/reference/#/p5/describe). This provides a concise, visual description for screen readers. |
There was a problem hiding this comment.
Minor: In the style of the rest of the doc, this can be 1 bullet point, followed by the bullet points of each of the best practices you have below
|
|
||
| **Do/Don’t Examples:** | ||
|
|
||
| | Do | Don’t | |
There was a problem hiding this comment.
In the style of the rest of this document, each of the above "best practices" should be illustrated with a "Good" and "Bad" example. Instead of splitting these and using sa table here, integrate illustrative examples in the list above.
|
|
||
| To make p5.js sketches accessible, every example that draws to the canvas should include a call to [`describe()`](https://p5js.org/reference/#/p5/describe). This provides a concise, visual description for screen readers. | ||
|
|
||
| **Best Practices for `describe()`:** |
There was a problem hiding this comment.
This line is not needed - the whole style guide tries to be as compact as possible
|
|
||
| - See the [Web Accessibility Contributor Doc](./web_accessibility.md#user-generated-accessible-canvas-descriptions) for technical details and examples. | ||
| - See the [Writing Accessible Canvas Descriptions tutorial](https://p5js.org/tutorials/writing-accessible-canvas-descriptions/) for more best practices and rationale. | ||
| - Reference examples must include a `describe()` call. See [Contributing to the p5.js Reference](./contributing_to_the_p5js_reference.md#add-a-canvas-description-using-describe) for details. |
There was a problem hiding this comment.
This should also not be repeated (this is not a universal suggestion - but the style guide tries to be very compact)
|
|
||
| **More Guidance:** | ||
|
|
||
| - See the [Web Accessibility Contributor Doc](./web_accessibility.md#user-generated-accessible-canvas-descriptions) for technical details and examples. |
There was a problem hiding this comment.
Minor: consider simpler and more direct language. "New to writing accessible canvas descriptions? Please check the Web Accessibility Contributor Doc and Writing Accessible Canvas Descriptions tutorial next."
|
|
||
| ### describe() | ||
|
|
||
| **See also:** [Documentation Style Guide: Canvas Accessibility Descriptions](./documentation_style_guide.md#canvas-accessibility-descriptions-describe) for best practices, Do/Don’t examples, and summary guidance on writing effective `describe()` calls. |
There was a problem hiding this comment.
Technically, this documentation is a more detailed doc than the above. What about something like: "describe() is one of the ways that p5.js sketches can be made accessible to screen readers. All contributions to the reference should include accessible canvas descriptions (see: Documentation Style Guide: Canvas Accessibility Descriptions)" - more focusing on the motivation of the style guide and its audience, than on passive description of its contents
|
|
||
| ### describe() | ||
|
|
||
| **See also:** [Documentation Style Guide: Canvas Accessibility Descriptions](./documentation_style_guide.md#canvas-accessibility-descriptions-describe) for best practices, Do/Don’t examples, and summary guidance on writing effective `describe()` calls. |
Addresses #6387
Changes:
describe().Details:
documentation_style_guide.md, including best practices, a Do/Don’t table, and links to additional resources.contributing_to_the_p5js_reference.mdandweb_accessibility.mdto make accessibility guidance more discoverable.ellipse()andline()) are missing or have weakdescribe()calls; this PR provides the groundwork for improving those examples.Closes: #6387
PR Checklist
npm run lintpasses