Edit docs for color

[nickmcintyre]

Increasing Access

I want to simplify the inline documentation for creating, reading, and setting color. There's also an opportunity to make the wording more consistent. Doing so would increase cognitive accessibility. It would also make documentation more approachable for young learners.

Most appropriate sub-area of p5.js?

• Accessibility
• Color
• Core/Environment/Rendering
• Data
• DOM
• Events
• Image
• IO
• Math
• Typography
• Utilities
• WebGL
• Build Process
• Unit Testing
• Internalization
• Friendly Errors
• Other (specify if possible)

Feature enhancement details

I'll make line edits to the inline documentation for this subset of the API.

[zelf0]

Can I help with this?

[nickmcintyre]

Sure! I'll open a pull request with the first batch of edits in a moment. This will give you a sense of how we're approaching the task.

In the meantime, please have a look at the guide for contributing documentation and the documentation style guide.

[nickmcintyre]

The next set of functions I had in mind are from the Setting section of the p5.js Reference:

background()
clear()
colorMode()
fill()
noFill()
noStroke()
stroke()
erase()
noErase()

I start by copying the current documentation into the Hemingway Editor. This helps me to identify complex sentences. It also lets me gauge the simplicity of my edits. I do my best to land around Grade 7.

[zelf0]

Great, looked at your pull request and will make a similar PR with edits to src/color/setting.js

[zelf0]

I see in the color() function, you changed "In this case, an alpha number value as a second argument is not supported, the RGBA form should be used. " to "The version of color() with two parameters interprets the first one as a
grayscale value. The second parameter sets the alpha (transparency) value." Does that mean the function changed to now support a second argument? If so, is it also now supported in any other functions, such as background()?

[nickmcintyre]

The color() function hasn't changed. That note didn't seem necessary after reorganizing a bit.

[zelf0]

Here's my current progress: main...zelf0:p5.js:edit-color-inline. I'm new to contributing so I may be doing something incorrectly.

[nickmcintyre]

We're always getting it at least a little bit wrong. Keeps things interesting :)

This is a great start. Consistency increases accessibility, so I have a few suggestions:

• Use American English: grey becomes gray
• Start comments with a capital letter and use punctuation: // Named SVG/CSS color string becomes // A CSS named color.
• List the different ways to call background() as I did with color():

The version of background() with one parameter...

The version of background() with two parameters...

And so on.

Let's see how these edits look. You may come up with a simpler/clearer approach as you write.

[zelf0]

Thanks so much for the feedback, I just committed a few tweaks

[zelf0]

Finished the 9 setting functions. Let me know if it looks good and I should submit a PR. main...zelf0:p5.js:edit-color-inline

[zelf0]

Should I submit a pull request?

[nickmcintyre]

These look good! Please go ahead and submit a PR. I'll probably edit them a bit after merging and will tag you to discuss the changes.

For a little perspective, I'm writing a calculus book and receive large batches of edits from my editor. We iterated on the opening chapters a few times before we settled on a style. I'm going to revisit some of my earlier edits to the p5.js docs based on ideas I'm borrowing from you.

[zelf0]

Oh also, I noticed we were changing variable declarations in the examples from let to const, so I was doing that as well where applicable, but then I saw in the inline documentation guide says to define all variables with let in code samples, so now I'm wondering whether to change them or not.

[nickmcintyre]

Thanks for pointing this out. Using let feels like the right call--please do so. I'll update the style guide later today.

[nickmcintyre]

Thanks for your help @zelf0!