processing
Multiple suggestions
[Ed: sorry, I should have called this "Multiple documentation suggestions" but can't see a way to edit the title.]
I wasn't sure exactly where to submit feedback and so a couple of weeks ago I posted the remarks below on the processing.org website. I heard back from jeremdouglass suggesting that I break these down into individual issues and submit here, perhaps along with PR. Unfortunately, I don't have time to do that. I am submitting here as is, please feel free to use or ignore. Great project! Nat Kuhn
Hi, I stumbled on p5.js because I wanted to use p5.sound on a React project. (I didn’t spot another sound library with the pan() feature, which I need.) It looks like a very cool resource and community. I can see that a huge amount of work has gone into it.
It took me quite a while to figure out what to do. The p5js.org 2 website is lovely, but hasn’t quite caught up with development, which means you are going to lose some possible audience. Here are some things I noticed:
a) the sidebar is not consistent; most pages include “Editor” but the “Reference” page does not p5js. org/reference/ (I have tried to put in links to everything I’ve identified but when I tried to post I was told I could only put in two links, so I will try to denature the other links by taking out https colon slash slash and putting a space after the first dot.)
b) the “Get Started” and “Download” pages are confusing and have duplication. The Download page acknowledges that it is mis-named. There are now several ways to get started that are easier than downloading. (you Editor, codepen, etc.) I would suggest refactoring these two pages, putting “Get Started” first.
c) I found what I needed on the p5 wiki github.com/processing/p5.js/wiki; however, there is no link to it from the “Learn” page, so I had to stumble on it.
d) In particular, I needed to use “instance mode” and this was the only place I could find it github. com/processing/p5.js/wiki/Global-and-instance-mode. I didn’t see a link to the wiki from the Learn page, which would have been helpful.
e) It was also helpful to use the npm module, which was not clearly documented. This was a particular problem for adding on p5.sound from the npm module. The answer was sprinkled throughout p5.js-sound issues on GitHub github. com/processing/p5.js-sound/issues/137. It would be great to have this clearly documented on the p5.js-sound GitHub repo as well.
f) I also stumbled on noCanvas(), and included it. Maybe it would have worked without it.
g) So maybe a page on “other ways to use p5.js” that includes at least links to something about global vs instance mode, maybe something on p5.dom, no canvas, using p5.sound stand-alone, using npm, etc.
h) the links to p5.sound and p5.dom at the top of the Libraries page are broken. At least the link to p5.sound at the top of the Reference page works, but there is no link to p5.dom there. So the only way to learn about p5.dom is by looking at individual classes/methods; there doesn’t seem to be an accessible overview.
Again, thanks for all the work that has gone into this. I did manage to get my project working. I hope that some of this is helpful! Best, Nat Kuhn
Thanks for the issue @natkuhn. It would be better to have them split out into individual issues but we can do that later. I'll answer the points you raised here for now.
a) The reference page is actually a separate webpage from the rest of the site to changes to the site in general doesn't always propogate to the reference page. I'm looking to make some changes here soon.
b) For me the two pages serve different purposes: "Get Started" is for people first encountering p5.js while "Download" is for people wanting to get a copy of the library locally (maybe to get the latest version). I get the duplication of content especially regarding the web editor, but the idea is that the two pages caters to two different audiences they still may have coinciding goals (getting to the web editor, setting up a project locally, etc)
c) That would be a good idea to include a direct link to the wiki in the "Learn" page. 👍
d) A link to that can probably be included in the "Becoming a better programmer" section
e) Requiring p5.js from the npm module is not something p5.js is specifically designed for and we have no tests to cover that so it isn't a recommended way to use p5.js, for now, it could be something we explore in the future but it isn't officially supported right now.
h) That needs to be fix. p5.dom is now part of the core library and so will not have its own tag in the reference.
Thanks, @limzykenneth , glad to know that these are in the hopper somewhere. Best of luck with it all.
@limzykenneth I would like to work on issue "c" can you guide me through it. Perhaps should I open a new issue regarding this?
connecting merged pull request for item c (wiki link): https://github.com/processing/p5.js-website/pull/526
connecting merged pull request for item h (fixed library links): https://github.com/processing/p5.js-website/pull/531