Documentation Style Guide suggestions

[dkessner]

Increasing Access

This a suggested restructuring of the Documentation Style Guide to give more emphasis to the goal of inclusivity and accessibility by moving the technical code style recommendations to a separate page.

Most appropriate sub-area of p5.js?

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

Feature enhancement details

1) I think it might be helpful to separate the "Writing" and "Code Sample" styles into two separate pages. The code sample style suggestions are very good, but also very technical, and they take up a lot of page real estate which takes away from the main message of the "Writing" section, which is to emphasize inclusivity and accessibility.

2) Also, the Documentation Style Guide doesn't appear in the left navigation bar -- it seems to only have a link from the "Contributing Documentation" page.

(I was asked to look at this page by @nickmcintyre)

[welcome[bot]]

Welcome! 👋 Thanks for opening your first issue here! And to ensure the community is able to respond to your issue, please make sure to fill out the inputs in the issue forms. Thank you!

[Qianqianye]

Thanks @dkessner! Both of suggestion sound great.

1. I agree that it could be helpful to separate the "Writing" and "Code Sample" styles into two separate pages. We are in the process of reviewing and optimizing all the files in contributor_docs folder, so we can seperate the "Writing" and "Code Sample" pages after the overall review.
2. We are also in the process of redesigning the p5.js website, so the navigation issue on the Contribute page is planned to be improved. Currently the Contribute page is direclty generated from the contributor_docs folder on p5.js GitHub.

I'm wondering if it'd make sense to add a session about Readability (not sure if it's right name) in the Writing part. We can set a goal to make sure all p5.js documentation is understandable for a 6th grader or so, like the Hemingwayapp's Readability Grade Levels suggests. What do you all think?

[nickmcintyre]

Agreed @dkessner and @Qianqianye! Separating the guide into two pages will make it easier for contributors to find what they need. And I like the idea of adding a section to emphasize our readability goal.

@dkessner how about you handle these two changes?

I'll follow up with pull request that adds a writing guide for tutorials.

[dkessner]

Sounds good @Qianqianye and @nickmcintyre. I agree that a Readability section would be useful. Q mentioned separating the pages "after the overall review" so I'll wait on any further action until we're ready.

[nickmcintyre]

Good call @dkessner. We're actually drafting a more comprehensive technical writing guide to cover different types of documentation. Thanks for pointing us in this direction! I'll open a pull request for you to review soon.

[Garima3110]

Hey there, I am just a beginner to open source but very passionate about learning and contributing to open source. I want to address this issue. Could you please guide me through the process. It would be very helpful for me.