Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improvements in Documentation #1353

Open
ranjanmangla1 opened this issue Apr 10, 2023 · 1 comment
Open

Improvements in Documentation #1353

ranjanmangla1 opened this issue Apr 10, 2023 · 1 comment

Comments

@ranjanmangla1
Copy link

ranjanmangla1 commented Apr 10, 2023

Increasing Access

The changes purposed will make the documentation more appealing, easy to follow and for new users (especially those who are new to programming), it would become easy for them to make sense of the things.
Documentation is not only for nerds, or the ones who are already familiar with the things. For a good development community, like NextJS, what I have found is, they have great docs.
But here, p5.js doc looks unwelcoming to me, like it directly dives into theory part, and it also lacks accessibilty as most of doc goes directly into the straight p5.js concepts. User does not get time to know, why they are learning it and what the will be doing with it, and how they should proceed, so p5.js's docs disappoints in this regard.

Most appropriate sub-area of p5.js?

Learn

Feature request details

I have gone through the doc of p5.js(learn part), it is great, it is to the point. But the problem here I have found is, IT IS TOO STRAIGHT TO THE POINT!

It's not that engaging!

If a new user comes in and he does not have a prior programming experience, it becomes much difficult for him to understand what's goimg on here.
The doc does not tell you, why are you learning it, what are the possible use cases (straighforwardly on the homepage or website itself, you have to dig it or search for it)
Instead there are seperate sections about various aspects of theory.

And another problem, is that the much of the doc is on github and doc pages have less accessibilty and it turns non programming people and kids, as the ui of github kind of becomes boring for them.
So, a doc on website itself becomes important and reduces confusion too!

And the BIGGEST ISSUE...The doc does not have a starter project, where by Building a Project you teach or give an overview of concepts. The Learn By Doing Approach should be incorporated here as well!

As in programming, it is often said that the best learning happens by building some stuff.

As part of p5.js community, it is our responsibility to create a doc, which is welcoming to all.
I hope the above changes will be accepted so that the doc becomes a pleasant experience.

So, in a nutshell, the action points are:

  1. Creating a beginners Learn By Doing Project in Doc (a tutorial, if possible, some informality in the language & some memes in it to keep people enagaged)
  2. Making the docs more user friendly
  3. Migrating all the docs to the website itself
  4. We can also add points based reward system like NextJS for tutorial, which gamifies the tutorial, so that readers have to complete it
@virusinlinux
Copy link

I want to contribute and make documentation easier for new peers to understand about p5.js

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants