This year with my mentor @tyler-yin, I’ve worked on updating the examples section of the p5js website. My goal with the project was to introduce examples which focus on programming constructs alongside concepts of art & design. My hope is that by showcasing how the tool can be used visually, I can bridge the gap that beginners often face between conceptualising an artwork and coding it.
I also propose a set of layout and functionality changes to the website that enhance the user experience. I believe the way the examples is currently structured can intimidate a lot of beginners from exploring and learning.
You can find my full proposal here.
I have so far been working on 5 of the 25+ categories present in the examples section.
These mainly involve : Color, Math, Image, Motion, Drawing, and Input.
I have structured my work in this notion document (https://malayvasa.notion.site/GSoC-2022-Examples-Project-ffee1e56ab1a4d7bb27b40ea7a145555) where you can view it category wise. There are two broad categories :
These are existing examples that I felt needed to be simplified or modified to make them easy to understand and inviting beginners to play with the code.
- Saturation : Editor Link
- Hue : Editor Link
- Brightness : Editor Link
- Lerp Color HSB : Editor Link
- Radial Gradient HSB : Editor Link
- Random : Editor Link
- Noise 2D : Editor Link
- Noise 3D : Editor Link
- Arctangent (Simple) : Editor Link
- Arctangent (Advanced) : Editor Link
- Distance 1D : Editor Link
- Sine Cosine : Editor Link
- Sine : Editor Link
- Parametric Equations (Simple) : Editor Link
- Additive Wave : Editor Link
- Image Transparency : Editor Link Alpha Mask : Editor Link
- Motion Reflection (Simple) : Editor Link
- Input Keyboard : Editor Link
- Form Lines : Editor Link
- Text Rotation : Editor Link
These are the examples that are not on the website, but I feel should be there. They broadly introduce new concepts that I’ve myself encountered.
- Color Wheel : Editor Link
- Monochromatic Color Sceme : Editor Link
- Responsive Text Fill : Editor Link
- Pixel Array Manipulation : Editor Link
- Dot Matrix Animation : Editor Link
- Circular : Editor Link
- Wave Maker : Editor Link
- Lyric Poem : Editor Link
Working on these I’ve developed guidelines to write a great example that anyone can follow as well :
Example code is an opportunity to directly influence how your users write code. Therefore, examples should showcase the best way to use your product
Example code should meet the following criteria:
- Free of any errors.
- Perform the task it claims to perform.
- Be as production-ready as possible.
- Follow language-specific conventions.
Examples should focus on explaining or demonstrating concepts that can be applied to a wide variety of scenarios. If you find writing a super specific example, ask yourself if writing a tutorial would be a better way to address it.
Examples are not tutorials. People already know what they are seeking from a tutorial, examples instead introduce people to what's possible.
As a beginner, seeing a page full of code can be very intimidating. To avoid this, examples should be kept as simple as possible.
Try and keep the pre-requisite knowledge to a minimum. Since an example is ideally being used to introduce a new concept or framework, the reader shouldn't have the added burden of figuring out other stuff which could be avoided.
In some cases, an example will require more complexity. Break it down further into three separate examples that address different experience levels Beginner, Intermediate & Advanced.
In the case of examples, comments almost form a dialogue with the code. This gives the reader a sense that someone is explaining the code to them.
Comments are also extremely helpful in introducing additional context. Clarity and understanding of the purpose of a particular line of code are important to avoid unwanted confusion.
Moreover, since the reader is exposed to well-documented code this will encourage them to add comments to their code as well.
This one is pretty simple, the example should invite the user to play around with the code.
This can be achieved by :
- Making the example intriguing, to invoke the thought "How did it do that?!"
- Using easy to understand variable names, although they might seem a bit verbose at times.
- Making the example editable, without the need of setting up a coding environment.
It doesn't matter how great your example is, if it isn't easy for the reader to find it. There are a few things you can do to improve discoverability :
- Have a descriptive name, it is possible many beginners aren't aware of a concept at all and using a technical name might hinder the process of discovery.
- Link your examples to the relevant sections of the documentation, and to other similar examples.
- Have a thumbnail, if contextually applicable.
I would like to thank Tyler, Saber and Qianqian. The project would not have reached this stage without the amazing guidance and support from them.