-
-
Notifications
You must be signed in to change notification settings - Fork 3.5k
Google Season of Docs
Welcome! This page contains a list of ideas and how you can help contribute to the Processing Foundation's work on p5.js for Google Season of Docs.
For all of our projects, it's incredibly important that things are kept as simple and user-friendly as possible. Our work is not for developers, it's for people who are less familiar with code, and/or just want to get things done. We're especially interested in documentation projects that lower the barrier to entry for new users or contributors and make it easier for them to get started.
In addition to this list, we track specific bugs and enhancements via github issues:
If you have questions about an idea or need guidance on forming your proposal, please post to the Processing Forum. This is the best way to get feedback and develop your idea. This makes it possible for everyone to learn from your questions and contribute their thoughts.
p5.js is a JavaScript library that starts with the original goal of Processing, to make coding accessible for artists, designers, educators, beginners, and reinterprets this for today's web. Using the original metaphor of a software sketchbook, p5.js has a full set of drawing functionality. However, you’re not limited to your drawing canvas, you can think of your whole browser page as your sketch! p5.js has addon libraries that make it easy to interact with other HTML5 objects, including text, input, video, webcam, and sound. p5.js is a new interpretation of Processing, not an emulation or port, and it is in active development.p5.js is a JavaScript library that starts with the original goal of Processing, to make coding accessible for artists, designers, educators, beginners, and reinterprets this for today's web. Using the original metaphor of a software sketchbook, p5.js has a full set of drawing functionality. However, you’re not limited to your drawing canvas, you can think of your whole browser page as your sketch! p5.js has addon libraries that make it easy to interact with other HTML5 objects, including text, input, video, webcam, and sound. p5.js is a new interpretation of Processing, not an emulation or port, and it is in active development.
Like any open source project, supporting and maintaining an active community of contributors is an essential part of p5.js. The main issue we are experiencing is that though we have many contributors, creation and maintenance of documentation has not been a priority. We have a standard README and onboarding documents, but they were written for more experienced developers and contributors, not for beginners or newer users.
One of our top priorities for p5.js entails bolstering the diversity of contributors in our community especially including those who may have never contributed to our codebases. By focusing on the onboarding experience, we will not only provide better documentation and a stronger community for current contributors, we will also expand the opportunities to include users who are interested but unsure of how to contribute.
We hope to work with 2 technical writers on the Onboarding New Contributors project, one focusing on improving documentation for new p5.js contributors, and one focusing on improving the Friendly Error System (FES) and documentation.
The Onboarding New Contributors project will focus on two key areas: 1) beginner usability of p5.js software and 2) FES documentation. Beginner Usability: How can the README, developer/contributor docs, and other documentation be improved to make it easier for new people to contribute, especially those without deep experience coding or contributing to open source? This may also involve looking at GitHub community communications and implementing structures that enable new contributors to get help in making their first pull requests. In addition to updating and modifying the current documentation, this role will include researching, proposing, and implementing new onboarding practices for new users, which could take the form of video tutorials, implementing additional accessibility features, etc. FES: The Friendly Error System (FES) is a system designed to help new programmers with common user errors as they get started learning. It catches common beginning errors and provides clear language and links to help a user resolve the error. This project would involve improving the FES documentation. This might mean things like updating the FES developer doc, and adding comments inline to the code. Another big goal we have is to add internationalization/localization to the FES so error messages may be given in different languages.
**Expected Tasks: **
- Meet with mentor to set project timeline and discuss expectations
- Review README and developer documentation for usability of beginners
- Make sure contributor docs are updated and in accordance with the current software version
- Research best practices for onboarding new contributors
- Create best practices document for new users based on aforementioned research phase
- For FES, working with translators to implement non-English language translations
- Share project findings with p5.js community (live-presentation or blog-post)
Project Timeline: Broadly speaking, we expect technical writers to be on the following schedule, however, the first week of work will include project mapping with mentors.
Month 1: Review all current contributor documentation and onboarding practices. Begin researching best practices for onboarding new contributors.
Month 2: Interview current key contributors about their past experiences as beginning contributors. Propose onboarding plan to mentors & administrators.
Month 3: Implement onboarding plan, finish updating documentation, prepare project findings presentation (live-presentation or blog-post to Processing Foundation Medium publication).
Skills Required:
- Javascript
- GitHub Experience
- Communication Skills
- Interest in community building
- Difficulty: For beginners, intermediate, or advanced users
Possible Mentors: Stalgia Grigg, Evelyn Masso, Saber Khan, Aáron Montoya-Moraga, and Kenneth Lim
As of March 2021, we have over 300 active contributors and 6 dedicated stewards. After completing the Onboarding New Contributors Project, we hope to gain an increase in the following metrics:
- Increase number of new contributors by 5% (based on our current active contributor base) one year after project completion
- Implementation of Onboarding New Contributors Project within two existing Processing Foundation programs, which are 1) the Creative Code Fest and 2) Processing Community Day
- Form a committee of 3-5 community members, in addition to the stewards, to focus on maintaining new user documentation
- A public write-up or presentation of lessons learned and future recommendations or the community, prepared by the Technical Writer
Budget Item
- Technical Writer: New Contributor Onboarding Experience $6000
- Technical writer will improve contributor docs, research and implement new community practices for beginning users.
- Technical Writer: Improve Friendly Error System (FES) & Documentation $6000
- Technical writer will improve documentation, provide updates to the FES overview doc and add comments inline to the code.
- Mentor Stipends $500 x 4 = $2000 (4 mentors x $500 each, 2 dedicated mentors per project)
TOTAL: $14,000
p5.js is a JavaScript library that starts with the original goal of Processing, to make coding accessible for artists, designers, educators, beginners, and reinterprets this for today's web. Using the original metaphor of a software sketchbook, p5.js has a full set of drawing functionality. However, you’re not limited to your drawing canvas, you can think of your whole browser page as your sketch! p5.js has addon libraries that make it easy to interact with other HTML5 objects, including text, input, video, webcam, and sound. p5.js is a new interpretation of Processing, not an emulation or port, and it is in active development.
This project involves thinking about the experience for new contributors to the project. How can the README, developer_docs, and other documentation be improved to make it easier for new people to contribute, especially those without deep experience coding or contributing to open source? This may also involve looking at github community communications and implementing structures that enable new contributors to get help in making their first pull requests.
- Expected Outcomes: Update of contributor docs, implementation of new community practices for facilitating beginners in contributing.
- Possible Mentors: Stalgia Grigg
- Skills Required: JavaScript, GitHub, communication skills
- Difficulty: beginner, intermediate, or advanced
In 2018 working with one of our Fellows, Vijith Assar (https://medium.com/processing-foundation/a-p5-js-dissection-manual-38959ff8522e), we began to add documentation throughout the github repository to aid in project navigation. This resulted in readme files in src/ directory folders like this and this, as well as a readme in the developer_docs/ directory that outlines the project structure. The goal of this project would be to extend this documentation to more of the repository, so it's easier for contributors to navigate the project and understand the purpose of the various files and pieces of code.
- Expected Outcomes: Update of contributor docs, implementation of new community practices for facilitating beginners in contributing.
- Possible Mentors: Lauren McCarthy
- Skills Required: JavaScript, GitHub, communication skills
- Difficulty: intermediate or advanced
Currently the p5.js website supports translations for Spanish and Simplified Chinese. Both of these could use updated translations for sections of the text. This page gives an overview of the translation process. Alternatively, a participant might propose adding another language that is not currently supported.
- Expected Outcomes: Update of p5js.org translations, or addition of a new language
- Skills Required: Fluency in a second language besides English, JavaScript, familiarity with Github or version control
- Difficulty: beginner, intermediate, or advanced
The Friendly Error System (FES) is a system designed to help new programmers with common user errors as they get started learning. It catches common beginning errors and provides clear language and links to help a user resolve the error. This project would involve improving the FES documentation. This might mean things like updating the FES developer doc, and adding comments inline to the code. Another big goal we have is to add internationalization/localization to the FES so error messages may be given in different languages.
- Expected Outcomes: Improvement of p5.js FES and documentation
- Skills Required: JavaScript, familiarity with Github or version control
- Possible Mentors: Evelyn Masso
- Difficulty: intermediate, advanced
p5.js Editor The p5.js Editor is a platform for creative coding, with a focus on making coding accessible for as many people as possible, including artists, designers, educators, beginners, and anyone who wants to learn. Simply by opening the website you can get started writing p5.js sketches without downloading or configuring anything. The editor is designed with simplicity in mind by limiting features and frills. We strive to listen to the community to drive the editor’s development, and to be intentional with every change. The editor is free and open-source.
Currently the p5.js Editor supports translations for Spanish, Japanese, and Hindi. A participant could translate the p5.js Editor to a language not currently supported. They could also translate the contributor docs, which have only been translated to Korean. They could also create a system for making sure translations stay in sync when there are changes to the p5.js Editor in English or the contributor docs in English.
- Expected Outcomes: A new editor.p5js.org translation, a new p5.js editor contributor docs translation, or a system to keep translations in sync
- Skills Required: Fluency in a second language besides English, JavaScript, familiarity with Github or version control
- Difficulty: beginner, intermediate, or advanced
The p5.js Editor is an open source project and therefore all of the source code is published. It is harder to publish the technical tools that are used to host the p5.js Editor at https://editor.p5js.org. Not only will documentation of all hosting tools and configurations help contributors to the project, it will help others to host their own instances if they choose to.
- Expected Outcomes: Detailed hosting documentation, self-hosting documentation
- Skills Required: Understanding of website hosting, familiarity with Github or version control
- Difficulty: intermediate
Right now, the only documentation of the p5.js Editor features exists in YouTube tutorial videos, which need to be updated as new features are added. Is there a different way to document features, perhaps using gifs? Is there a way to link to this documentation from the p5.js Editor?
- Expected Outcomes: Documentation of p5.js Features
- Skills Required: Familiarity with p5.js and programming
- Difficulty: beginner
The p5.js Editor includes a lot of code and a lot of different libraries. It would be useful to new contributors to document the project structure, as well as all of the different code libraries that are being used.
- Expected Outcomes: Documentation of p5.js Editor codebase
- Skills required: JavaScript, familiarity with Github or version control
- Difficulty: beginner, intermediate
If you would like to edit this wiki and don't already have edit access, please open an issue or comment on an existing one noting the wiki page you'd like to edit. You will then be added as a repository contributor with edit access.