Add guideline to use describe()

[Qianqianye]

Topic

We are in the process of including describe() in all reference code, as mentioned in the issue #5139: Use describe() to create accessible canvas descriptions in inline documentation.

I think creating a guideline to use describe() would be really helpful. This guideline will not only help contributors but also users (as mentioned in issue #5427) to write description.

@katlich112358 recently wrote a wonderful tutorial about 'How to label your p5.js code', which include some guideline like: "Within reason, less is more with screen reader labeling. Be concise, accurate, and short with your label descriptions." In the Pull Request #5599, @lm-n suggested that 'It'd be great if none of the descriptions are more than 3 lines long.'

We can create a more detailed guideline which includes recommended length of description, recommended and non-recommended examples of using describe(), etc. The 'Image Description Guide' created by @natdecker could be a great reference. The guideline could either be included in the 'How to label your p5.js code' tutorial or documentation_style_guide.md initiated by @nickmcintyre.

Would love to hear what you all think!

CC: @limzykenneth @davepagurek @katlich112358 @calebfoss @paulaxisabel @nickmcintyre @cosmicbhejafry

[katlich112358]

@Qianqianye I really like this idea-- based on how technical @nickmcintyre's syntax guide is, I think this level of detail for labeling would fit well in that guide (or another document stored in the same area-- maybe a document specifically centered around these more a11y technical instructions?). I can add references to the syntax guide in 'How to label your p5.js code', and really focus the tutorial around explaining the differences between the labeling functions, and then link any super specific instruction to the guide. How does that sound, y'all?

[davepagurek]

I think having a guide for that would be helpful @katlich112358! Especially for readers like myself who don't regularly use tools that read those descriptions and don't have an intuition for what makes for a good one. If we make a style guide for these, maybe we could add a bit of context to motivate our decisions, like how screen readers navigate through descriptions? (e.g. is describe like a quick high level overview before optionally drilling down into the details from describeElement?)

[nickmcintyre]

Agreed, this is a great idea!

@katlich112358 I like your suggestions for adding syntax references to How to label your p5.js code and creating a dedicated document around a11y instructions. It will probably be easier for folks to find and process the info this way. Perhaps you can add a guideline to use describe() wherever possible/appropriate to the Documentation Style Guide that references your new document.

[katlich112358]

@davepagurek @nickmcintyre awesome, I'll do some looking around at other library docs and see how to better restructure the labeling info 👍 are there any other aspects of the labels y'all are curious about, or just about ARIA labels in general? Just trying to get a better read about some of the questions p5 users might have regarding labeling and fallback content.

[saurabhsingh-7]

I am really confident that I can add guidelines regarding it. please assigne this issue to me. So that I can start the work ASAP.

[Qianqianye]

Thanks @saurabhsingh-7 for your interests in working on it. Before we get started, I'm wondering if @katlich112358 could share some the research about labels as mentioned in a previous comment in this issue?

Also @saurabhsingh-7, can you share with us your some of thoughts on the guideline? Like what you are planning to include? Thank you!

[katlich112358]

Apologies for the wait, here’s what I found looking around at other documentation sites:

Dev websites

• W3C has a lot of different ways you can learn about accessibility pursuits, all at different levels of abstraction and brevity. They usually have an in-progress abstract document which then links to individual reference guides for whatever tag or requirement mentioned. They’re very sure to mention versioning and the status and iterations of this content in these documents. Setbacks: VERY technical, and very heavy documentation to read if you’re new to accessibility and coding.
• W3C Schools is the more quick-use documentation source, with a very brief what, how, and why section listed at the top of individual tag references. They always have clear example code blocks and visual examples of the code, if applicable.
  Setbacks: The way the information about the tags represented is brief, and it might not lead to a full understanding of how all these parts work together to create one cohesive accessible experience-- in other words, the information is divided and organized in a way that it doesn’t lead well into understanding how one accessibility pursuit, such modifying the tabbing sequence, might also impact screen readers and ARIA roles.
• mdn web docs, like W3C, provides very detailed explanations of different tags (specifically the ARIA accessibility tags), only these docs bunker down on code examples and the importance of context when using these tags.
  Setbacks: These docs are also VERY technical and hard to understand if you don’t have a solid understanding of ARIA to begin with. That said, in my opinion, they offer one of the better super-detailed descriptions of ARIA labeling and tags.

JS libraries and frameworks
Overall, most JS libraries and frameworks link to W3C in order to better explain coding syntax or accessibility strategies in their docs. However, there’s usually a separate file in their documentation for some quick discussion about the importance of accessibility and using the library as intended. This is also the same strategy for design systems, which also may have specific accessibility notes on each component’s individual page.

Now, it seems like our current idea of separating the Learn overview content from the more technical syntax guide follows what other documentation sites are doing, which is great news! If this strategy for IA works, then I believe this strategy could be applied to other Learn examples and Reference pages as well in the future.

There are a few things to consider when expanding on the describe() instructions:

• When it comes to assistive text-- alt text, ARIA labeling, etc.-- the descriptions heavily rely on context (which is explained wonderfully by WebAIM’s article). Labeling is more of an art form, and not a science, where there’s only one right answer. I expect it will be hard to get fairly specific about the syntax strategies for labeling, but I do see having general rules such as the one @lm-n su mentioned in docs(src/webgl): Use describe() instead of @alt #5599 being pretty helpful in most use cases.
• The first rule for ARIA is to only use it when necessary, and to take advantage of built-in semantics or behavior for HTML elements. (In the Learn example, I can emphasize this better for any buttons or native HTML elements added in a canvas.)
• We don’t need to reinvent the wheel. Like other libraries, if W3C has adequate explanations about certain labeling practices, we can reference their guides and use primary sources for accessibility advice as much as possible.

That said, this is what I think to be the best order moving forward with this issue, and I’d love any feedback or input from y’all:

With the Learn page
This page could be more about emphasizing the more abstract and overarching reasons as to why labeling is important, referencing the technical syntax guide when needed. We could also try making this page more story-inclined, to potentially better express why it’s important to label your code and how someone using a screen reader might see your code (make it more user story-based, to help newer coders build empathy and a moral attachment for accessibility in general).

With the technical syntax page
This page can get into the weeds of how to label, and reference the W3C guide(s) when useful. Like other doc sites, adding multiple use cases and do’s and don’ts sections could help better express the importance of understanding the contextual and synergy of accessibility beyond the p5 canvas.

And if I need to clarify or rephrase anything, please let me know.

Thanks!

[Atharva-Kanherkar]

Hi! After reading the issue and studying it a little bit, here's what i got and what i can try to do:
1.Provide examples of descriptions that are overly verbose, unclear, or misleading. This can help users understand what to avoid.
2.: Provide examples of when to use describe(). This could include situations where an element's function or purpose may not be immediately obvious from its name or context. (i will have to study about this a little bit, and discuss)
3. : If the tutorial by @katlich112358 contains relevant information, maybe i provide a link to it within the guideline for those who want a more in-depth guide? (Not sure, but i think its a good idea?)
Also, can you please clarify how and where describe() should be included within your codebase? Should it be added directly within the code or as comments in the documentation?
And obviously, the short length and clarity will go hand by hand.