Add a style guide for writing and code in the p5.js docs

[nickmcintyre]

Topic

Hello! I propose creating a style guide for written explanations and code snippets. My goal is to ensure that all Reference and Example pages are clear and consistent. I plan to edit the Contributing Documentation guide to include a remix of the Ruby on Rails API documentation guidelines.

Writing

I'll follow the new writing style guide as I edit documentation over the coming months. The following references will be top of mind:

• Overview: Write the Docs
• General: Red Hat Supplementary Style Guide
• Accessibility: MDN What is accessibility?
• Reducing Bias: WordPress Inclusivity

I'll use the Hemingway Editor to ensure that the documentation uses simple language.

Code

I propose following the Airbnb JavaScript Style Guide for code snippets. I also plan to use Prettier to format code so that it matches the output of the p5 Editor's "Tidy" button.

I'd love to incorporate folks' suggestions as I draft the style guide. @davepagurek @limzykenneth @Qianqianye @raclim what do y'all think about testing this idea in a couple of steps? I can start by drafting the style guide. Then we can try an example of how the guide would change the Reference pages for 2D Primitives.

[Qianqianye]

Thanks @nickmcintyre for initiating this discussion. To share some context, Nick is the p5.js 2023 Season of Docs technical writer working on improving the Reference and Example page on p5.js website. Nick will work with mentor @davepagurek and advisor Jaleesa till the end of October this year.

I think it'd be great to include the style guide in the contributor_docs folder in this repo. The current design_principles.md file might be a good reference for the style guide.

I will also invite @SableRaf to this discussion to share some style guide related experience from Processing. Thanks!

[limzykenneth]

@nickmcintyre A quick note before I look into the relevant parts more, prettier was previously included as part of our toolchain but has been deliberately removed because of several reasons. The first is that its very slow, especially on a larger codebase such as ours. The other reason is that some of its formatting rules create excessive noise in the codebase (eg. adding lots of brackets) and can make things very hard to read, ignoring selectively also adds a lot of noise throughout the codebase.

The alternative we go with is to use eslint-fix which also means we can have more control over details as well as using a tool we are already using without needing to bring in another one.

[davepagurek]

Thanks @nickmcintyre! I think those steps sound good. For @limzykenneth's point, maybe we can manually format the examples for now so we have to worry yet about updating project configuration.

[SableRaf]

Thanks @nickmcintyre for the writeup and great references! I'll ping @WillRabalais04 who is working this GSoC on implementing friendlier error messages in Processing 4 as these are connected topics.

[nickmcintyre]

@limzykenneth I appreciate the context around tooling. I read through the Steward Guidelines and broke a few Reference samples to get a sense of how npm run lint:samples works. Glad this is already in place! I'll open a separate issue in the website repo for linting the Examples.

And good suggestion @davepagurek. I'll code in the p5 Editor before running samples and examples through ESLint.

[nickmcintyre]

Resolved by #6206