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 https://github.com/processing/p5.js/pull/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.

[NalinDalal]

Hi,

I’d like to take on drafting the guideline for using describe() in p5.js. Here’s the approach I’m thinking:

1. General Rules

• Keep descriptions concise (aim for 1 sentence or under 3 lines).
• Focus on the key content or behaviour; avoid redundant or overly detailed info.
• Use plain, clear language that’s easy for screen readers to convey.

2. Examples

• Do’s: show short, clear, context-aware descriptions.
• Don’ts: show overly long, vague, or redundant descriptions.

3. When to use / not use

• Use describe() for meaningful visual content or interactive elements (e.g., shapes, buttons, sliders).
• Avoid it for purely decorative or obvious elements.

4. References

• Link to Katlich’s “How to label your p5.js code” tutorial for deeper explanation.
• Reference W3C / WebAIM guides where applicable for accessibility best practices.

5. Placement

• Add this section to documentation_style_guide.md.
• Cross-link from the Learn tutorial so users can easily find the technical guidance.

I can start drafting this guideline and include concrete examples to illustrate best practices. Would love feedback on this approach before I begin

[lm-n]

@NalinDalal that looks like a great approach! I would also encourage you to add an example for each point

[ksen0]

Hi @NalinDalal thanks for volunteering to work on this, and thanks for sharing your plan first.

A little bit of feedback: The “How to label your p5.js code” link no longer works. But there are multiple resources: including the contributor docs on web accessibility, the contributor docs on adding to the reference which mention describe(), and the tutorial on writing accessible canvas descriptions. In this tutorial, the guidance is:

"No matter how complicated your project may be, always provide a brief description of your canvas in setup() using the describe() function. Within the describe() function, provide a 1-3 sentence description of your canvas in its text parameter. This description should only provide details about the visual elements of your canvas."

Although there are numerous resources (so no new specific resource needs to be created), this issue is still open to improve the visibility of these resources and guidelines. If you want to work on this issue, you could:

1. Go through JSDoc reference and find code examples that have missing describe() calls, or improving the descriptions there
2. If it seems relevant, you could also propose uses of describeElement() in the documentation
3. Make sure that the resources are well-linked in all the places where they are appropriate - eg, if there are places in other contributor docs that should link, you could suggest those
4. Review those resources and if there are any contradictions or unclarities, suggest updates. (But keep in mind that this is not about rewriting or significantly changing the existing guidelines, unless it's necessary)

I can also recommend reading all the guidelines linked above if any of them are new to you, and trying out a screen reader to browse the p5j5.org website if you haven't already.

From @katlich112358's comment above:

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.

This, too, emphasizes that it's important now is to motivate the use of accessible descriptions, and to explain/demonstrate how to write them and include them in sketches. That may be a helpful way to approach any changes you propose to existing docs.

What do you think about this approach @NalinDalal ?

[NalinDalal]

Thanks @ksen0 🙏, that’s really helpful. I’ll adjust my approach accordingly:

• Review the existing resources and make sure they’re consistent
• Add clear examples (Do/Don’t)
• Audit the JSDoc reference for missing/improvable describe() calls
• Suggest better linking across tutorials and contributor docs

[NalinDalal]

I reviewed the tutorial and contributor docs and I found no contradictions. I also checked JSDoc reference examples and found a few missing or weak describe() calls (e.g., ellipse(), line()). I’m preparing a PR to add concise, visual descriptions (under 3 lines) and to cross-link accessibility guidance across the docs.