Season of Docs 2023 Organization Application: p5.js
🌸 Hello! p5.js is applying for Season of Docs this year. Below is our application.
p5.js is a free open-source JavaScript library for creative coding, which focuses on making coding accessible and inclusive for artists, designers, educators, and beginners. Using the metaphor of a sketch, p5.js provides a full set of drawing functionalities, along with features using text, input, video, webcam, and sound. With over 1.5 million users worldwide, including students from K12 to universities, p5.js has become a popular tool for hobbyists and professionals alike. Access, inclusion, and diversity are the core values guiding the p5.js project and community.
The p5.js project has fostered a thriving and engaged community on GitHub, with 19.1k GitHub stars, 2.8k forks, and over 500 contributors.
The p5.js library has become increasingly popular among beginners who are learning to code in JavaScript. However, the current reference and example documentation, while comprehensive, can be overwhelming and difficult to navigate for users who are new to programming or p5.js. Challenges the documentation faces include: 1) unclear organization of information architecture, 2) assumptions of prior knowledge of programming concepts, and 3) inconsistencies in writing style.
Improving the reference and example documentation is crucial for p5.js and its community. The proposed project will ensure that the library’s documentation is well-organized, beginner-friendly, up-to-date, and consistent by implementing a clear structure based on community feedback, using simple language, avoiding technical jargon, and providing beginner-friendly examples and explanations. By improving the documentation, users of all levels will be able to learn p5.js more easily, reducing frustration and improving their confidence in using the library. Ultimately, this will help promote the growth and development of the p5.js community, which is essential for the project's long-term sustainability.
The "Improve p5.js Reference and Example Docs" project aims to:
- Conduct an audit of the existing reference (https://p5js.org/reference/) and example (https://p5js.org/examples/) documentation for organization, simplicity, and consistency.
- Create a friction log for the current documentation based on specific use cases, such as learning p5.js as a beginner and teaching p5.js to beginners.
- Gather feedback from documentation testers (including volunteers in the project) and the wider p5.js community.
- Use the friction log and community feedback as a guide to update the structure, descriptions, and examples on reference and example pages to ensure that they are accessible, beginner-friendly, and up-to-date with the latest software version.
- Share project findings with the p5.js community through a live presentation or blog post.
Work that is out-of-scope for this project:
- This project will not add new references.
- Familiarity with JavaScript and p5.js
- Experience with GitHub
- Experience teaching p5.js to beginners, either in K12 and/or college
- Experience writing coding tutorials for beginners
- Communication skills
- Project management skills
- Commitment to community building
Update on May 4: We have hired the technical writer, mentor and advisor for 2023, which are shown below.
Writer: Nick McIntyre
Mentor: Dave Pagurek
Advisor: Jaleesa Trapp
With support from p5.js Project Lead: Qianqian Ye
To measure the success of our project, we will track four key metrics related to the reference and example documentation:
- A 10% decrease in the number of out-of-date or beginner-unfriendly subpages in the reference and examples documentation.
- A 10% decrease in the number of GitHub issues raised for topics covered in the reference and examples documentation.
- A 10% increase in the number of page visitors to the p5.js reference and examples documentation.
- A 10% increase in the number of contributions to the reference and examples documentation on GitHub.
The project itself will take approximately about six months to complete, with 250 working hours in total. Once the technical writer is hired, we'll spend a month on technical writer orientation and project mapping, then move onto the audit and friction log, and spend the last few months focusing on improving the documentation.
| Dates | Action Items |
|---|---|
| May | Orientation and project mapping with mentor, review the existing reference and example docs |
| June | Audit existing documentation, conduct interviews and tests with community testers, create friction log, and identify gaps and areas for improvement. |
| July - October | Improve the documentation structure, description and example based on the friction log |
| November | Project completion, and share project findings presentation (live-presentation or blog-post to Processing Foundation Medium publication and social media) |
Our proposed budget:
| Budget Item | Amount | Running Total | Notes |
|---|---|---|---|
| Technical Writer - p5.js Contributor Docs Organization & Development | $12,500 | $12,500 | The technical writer will audit, update, test, and publish p5.js reference and example pages. |
| Mentor Stipends | $1,000 | $13,500 | |
| Community Testers Honorarium | $1,500 | $15,000 | 10 Community Tester x $150 each ($50 hr x 3 hours) |
| TOTAL | $15,000 |
TOTAL: 15000.00
The p5.js project has been an active participant in Google Season of Docs, having participated in both 2021 and 2022. In 2022, Kenneth Lim worked on the "Organize and Develop p5.js Contributor Docs" project, while in 2021, Ashley Jane Lewis and Alm Chung worked on the "New p5.js Contributors Onboarding Documentation" and "p5.js Friendly Error System Documentation" projects, respectively. You can read more about these projects in the published case studies (2022 case study, 2021 case study).
Since 2013, p5.js has mentored over 100 contributors through various programs, including Google Summer of Code, Rails Girls Summer of Code, and our own Fellowship Program. Many of these projects have focused on documentation, which is a critical aspect of both the user-facing and contributor-facing aspects of the p5.js project. Nick McIntyre, a potential technical writer for this year's proposed project, served as a mentor for the Dynamic Learning and p5.teach.js projects through Google Summer of Code.
Another collaboration with a technical writer took place in 2018 working with one of our Fellows, Vijith Assar. Over a period of six months, Vijith worked closely with his mentor Lauren McCarthy to survey the contributor-facing documentation and document the layout of the github repository, guiding design principles, and contributor docs. Through this work we were able to significantly increase the number of contributors and their ease of working on the project.
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.