The p5.js Reference Pages Are Bad

See why q5 is better for beginners and CS educators.

Check out q5’s documentation!

https://q5js.org/learn

The p5.js reference pages are bad…

p5.js reference pages (November 24, 2024)

… and not merely due to the garish color theming and sloppy formatting errors introduced in the recent website redesign.

They’ve always been bad.

Wait! Let me explain! 😅

Fixing the Fundamental Flaw

Don’t get me wrong, I appreciate all the work that’s been done by p5's contributors over the years. Yet there’s a fundamental flaw with the docs.

Can you tell what it is just by reading this excerpt?

This is often called the “draw loop” because p5.js calls the code in draw() in a loop behind the scenes. By default, draw() tries to run 60 times per second. The actual rate depends on many factors. The drawing rate, called the “frame rate”, can be controlled by calling frameRate(). The number of times draw() has run is stored in the system variable frameCount().

Code placed within draw() begins looping after setup() runs. draw() will run until the user closes the sketch. draw() can be stopped by calling the noLoop() function. draw() can be resumed by calling the loop() function.

— https://p5js.org/reference/p5/draw/

There are some minor mistakes. Saying that draw() tries to run 60 times per second is odd phrasing. Also frameCount is not a function. But the big problem is… the whole excerpt is boring, lengthy exposition!

Surely there’s a better way to present this info to beginners. What’s the fix?

Show Don’t Tell

“Show don’t tell” is the golden rule of writing. So why not show readers what all these related functions do?

The writers of the p5 docs constantly trip themselves up by making false generalizations. Then editors transplant nuance and divulge every possible caveat to those previous statements.

If a page starts with “The sun shines on the earth”, it then goes on to say, “Except not as much when it’s cloudy, night time, or during a solar eclipse.” Woah woah woah, I just wanted to know what the sun does. How about we start with, “The sun shines”. Then if users want to learn about Earth’s climate and celestial events they can scroll down to that info.

Recursive Redundancy

Look at this long example for redraw from p5js.org:

// Double-click the canvas to move the circle.

let x = 0;

function setup() {
  createCanvas(100, 100);

  // Turn off the draw loop.
  noLoop();

  describe(
    'A white half-circle on the left edge of a gray square. The circle moves a little to the right when the user double-clicks.'
  );
}

function draw() {
  background(200);

  // Draw the circle.
  circle(x, 50, 20);

  // Increment x.
  x += 5;
}

// Run the draw loop when the user double-clicks.
function doubleClicked() {
  redraw();
}

Notice how there’s five comments verbosely explaining what functions other than redraw do. Imagine if a dictionary had recursive definitions for the words in each definition!

With the mini code editors on the q5 Learn pages, users can hover over a function view inline documentation (big thanks to @Tezumie). What value then would comments like “Turn off the draw loop.” and “Draw a circle.” provide? Each example doesn’t need to be a stand-alone demo.

If you’d indulge me, subject yourself to all these pages on core functions:

• https://p5js.org/reference/p5/draw/

• https://p5js.org/reference/p5/setup/

• https://p5js.org/reference/p5/preload/

• https://p5js.org/reference/p5/noLoop/

• https://p5js.org/reference/p5/loop/

• https://p5js.org/reference/p5/redraw/

• https://p5js.org/reference/p5/frameCount/

• https://p5js.org/reference/p5/frameRate/

• https://p5js.org/reference/p5/getTargetFrameRate/

Redundancy to this extent makes it harder to gain pertinent information. Who wants to read through all this? I’m not just cherrypicking either.

Writing is Rewriting

Begging for a complete rewrite of the documentation was not going to pan out. It took five months just for one of my simple PRs to be included in a release of p5.js!

But as Captain Jack Sparrow said, “It’ll all have to be redone. All of it!”

Yes, I realize this idea sounds insane. How could I expect to do better than the combined efforts of hundreds of p5 contributors?

Mark Twain once wrote, “Sorry I didn’t have time to write a short letter”. Writing is an art! Concise writing takes a lot of effort and planning.

So my big plan for q5’s documentation was to group documentation for related functions into scrollable sections. Each function definition and code example can therefore be written as part of a sequence.

Making Mini Examples

Here are the strategies I used when writing the code examples in q5.d.ts.

• Keep ’em short and sweet, the average example is just 6 lines of code!

• Avoid defining a setup function, use createCanvas to start the sketch or only write a draw function.

• Avoid declaring and using variables.

• Don’t add comments explaining other functions (users can hover for documentation).

• Use comments in the code only when necessary. Don’t use the describe function in the code, all explanation should be given in the JSDoc.

• When user interaction would enhance the example, stick to simple interactions: moving the mouse, pressing left mouse button, or pressing the space key.

Following these guidelines, this example code retains the essence of the p5 example, but cuts it from 29 lines to just 8.

function draw() {
  circle(frameCount * 5, 50, 20);
  noLoop();
}

function mouseClicked() {
  redraw();
}

Alright, had enough yapping? Check out the “core section” of q5’s documentation!

https://q5js.org/learn

Note how the descriptions are not overly broad, to avoid pesky false generalizations. For example the description for draw simply states “The draw function is run 60 times per second by default.” Putting “by default” makes it so I don’t have to account for any exceptions right away. If users want to change the default behavior, they’re inclined to read more: and that’s actually a good thing!