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.