Improve Accessibility Guidance for describe() Usage

contributor_docs/contributing_to_the_p5js_reference.md

@@ -308,7 +308,11 @@ Finally, for every example you add, you are required to use the p5.js function `
 * </div>
 ```
 
-For more on `describe()` visit the [web accessibility contributor documentation](./web_accessibility/#describe).
+
+For more on writing effective `describe()` calls:
+- 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 best practices and rationale.
+- See the [Documentation Style Guide section on describe()](./documentation_style_guide.md#canvas-accessibility-descriptions-describe) for Do/Don’t examples and summary guidance.
 
 With all the above you should have most of the tools needed to write and edit p5.js reference comments. However, there are a few more specialized usage of JSDoc style reference comments that you may come across in p5.js. These are situationally useful and not something that you need often.
 

contributor_docs/documentation_style_guide.md

@@ -23,23 +23,34 @@ Our community is large and diverse. Many people learn to code using p5.js, and a
 - [Accessibility and Disability](#accessibility-and-disability)
 
 ### Code
-- [Code Samples](#code-samples)
-- [Comments](#comments)
-- [Whitespace](#whitespace)
-- [Semicolons](#semicolons)
-- [Naming Conventions](#naming-conventions)
-- [Variables](#variables)
-- [Strings](#strings)
-- [Boolean Operators](#boolean-operators)
-- [Conditionals](#conditionals)
-- [Iteration](#iteration)
-- [Objects](#objects)
-- [Arrays](#arrays)
-- [Functions](#functions)
-- [Arrow Functions](#arrow-functions)
-- [Chaining](#chaining)
-- [Classes](#classes)
-- [Assets](#assets)
+- [Documentation Style Guide](#documentation-style-guide)
+  - [Table of Contents](#table-of-contents)
+    - [Writing](#writing)
+    - [Code](#code)
+  - [YUIDoc](#yuidoc)
+  - [English](#english)
+  - [Oxford Comma](#oxford-comma)
+  - [Wording](#wording)
+  - [Unbiased Documentation](#unbiased-documentation)
+  - [Accessibility and Disability](#accessibility-and-disability)
+  - [Code Samples](#code-samples)
+  - [Comments](#comments)
+  - [Accessible Descriptions](#accessible-descriptions)
+  - [Whitespace](#whitespace)
+  - [Semicolons](#semicolons)
+  - [Naming Conventions](#naming-conventions)
+  - [Variables](#variables)
+  - [Strings](#strings)
+  - [Boolean Operators](#boolean-operators)
+  - [Conditionals](#conditionals)
+  - [Iteration](#iteration)
+  - [Objects](#objects)
+  - [Arrays](#arrays)
+  - [Functions](#functions)
+  - [Arrow Functions](#arrow-functions)
+  - [Chaining](#chaining)
+  - [Classes](#classes)
+  - [Assets](#assets)
 
 ## YUIDoc
 
@@ -165,7 +176,7 @@ Choose meaningful code samples that cover the basics as well as gotchas. Only us
 
 ```javascript
 // Bad.
-let magicWord = 'Please';  // Remember this.
+let magicWord = 'Please';  //Remember this.
 
 // Good.
 // Remember this.
@@ -174,7 +185,7 @@ let magicWord = 'Please';
 // Bad.
 if (keyIsPressed === true) {
   thing1();
-  // This is an important note.
+  //This is an important note.
   thing2();
 }
 
@@ -204,22 +215,13 @@ let magicWord = 'Please';
 ```javascript
 
 // Bad.
-/**
- * I will use // for multiline comments.
- * I will use // for multiline comments.
- * I will use // for multiline comments.
- * I will use // for multiline comments.
- * I will use // for multiline comments.
- */
-
-//Bad.
 /*
- I will use // for multiline comments.
- I will use // for multiline comments.
- I will use // for multiline comments.
- I will use // for multiline comments.
- I will use // for multiline comments.
- */
+I will use // for multiline comments.
+I will use // for multiline comments.
+I will use // for multiline comments.
+I will use // for multiline comments.
+I will use // for multiline comments.
+*/
 
 // Good.
 // I will use // for multiline comments.
@@ -230,6 +232,29 @@ let magicWord = 'Please';
 
 ```
 
+
+## Accessible Descriptions
+
+- Use `describe()` to make p5.js sketches accessible to screen readers. All reference contributions should include a concise, visual canvas description for accessibility.
+
+- **Concise:** 1–3 sentences. Briefly describe what is visually present on the canvas.
+  - Good: `describe('A blue rectangle in the center of a white canvas.');`
+  - Bad: `describe('This code draws a rectangle.');`
+
+- **Visual-Only:** Focus on what a sighted user would see. Do not describe code, instructions, or interactions unless they are visually represented.
+  - Good: `describe('A red heart and yellow circle over a pink background.');`
+  - Bad: `describe('Click to draw a heart.');`
+
+- **Non-Redundant:** Avoid repeating information already available in the title or code comments.
+  - Good: `describe('A black dot moves from bottom to top on a gray square.');`
+  - Bad: `describe('A shape.');`
+
+- **Clarity:** Use simple, direct language. End with punctuation for screen reader clarity.
+  - Good: `describe('A green triangle on a white background.');`
+  - Bad: `describe('triangle');`
+
+New to writing accessible canvas descriptions? Please check the [Web Accessibility Contributor Doc](./web_accessibility.md#user-generated-accessible-canvas-descriptions) and [Writing Accessible Canvas Descriptions tutorial](https://p5js.org/tutorials/writing-accessible-canvas-descriptions/) next.
+
 **[⬆ back to top](#table-of-contents)**
 
 ## Whitespace
@@ -1222,25 +1247,11 @@ class Mover {
 
 ## Assets
 
-- Always load assets from a folder called "assets".
-
 > Why? It models good project organization. It's also required for assets to load on the p5.js website. Place assets in the following folders to include them in our online documentation:
 - Examples: [src/data/examples/assets](https://github.com/processing/p5.js-website/tree/main/src/data/examples)
 - Reference Pages: [src/templates/pages/reference/assets](https://github.com/processing/p5.js-website/tree/main/src/templates/pages/reference/assets)
 - Learn Pages: [src/assets/learn](https://github.com/processing/p5.js-website/tree/main/src/assets/learn)
 
 ```javascript
-let img;
 
-// Bad.
-function preload() {
-  img = loadImage('moonwalk.jpg');
-}
-
-// Good.
-function preload() {
-  img = loadImage('assets/moonwalk.jpg');
-}
-```
-
-**[⬆ back to top](#table-of-contents)**
+ Always load assets from a folder called "assets".

contributor_docs/web_accessibility.md

@@ -242,6 +242,8 @@ When creating screen reader-accessible outputs, naming the colors used in the ca
 
 ### 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.
+
 The `describe()` function creates a sketch author-defined screen reader accessible description for the canvas. The first parameter should be a string with a description of the canvas. The second parameter is optional. If specified, it determines how the description is displayed. If a user passes `LABEL` as a second parameter, an additional `<div>` element is created next to the `<canvas>` element. The new `<div>` element contains a visible version of the same screen reader-accessible description embedded in the `<canvas>` element.
 
 `describe()` is supported by several methods in [src/accessibility/describe.js](https://github.com/processing/p5.js/blob/main/src/accessibility/describe.js):

src/type/textCore.js

@@ -2731,4 +2731,4 @@ export default textCore;
 
 if (typeof p5 !== 'undefined') {
   textCore(p5, p5.prototype);
-}
+}