-
-
Notifications
You must be signed in to change notification settings - Fork 3.3k
p5.js 2022 Google Season of Docs Case Study
2022 Google Season of Docs Case Study
Organization or Project: p5.js
Organization Description: 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.
Authors: Qianqian Ye, Kenneth Lim
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. There currently are different types of contributor docs in the p5.js GitHub repository and p5.js Website GitHub repository, like access statement, project note, roadmap docs, etc. It can be difficult for contributors to navigate the existing contributor doc structure in the two repositories.
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 contributor doc organization and development, 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 one technical writer on the p5.js Contributor Docs Organization & Development Project, focusing on organizing the existing contributor docs, and creating new contributor docs based on research.
A brief summary of your original organization proposal. Link to the proposal page on your project site, if possible.
You can access our original proposal at this link.
The p5.js Contributor Docs Organization & Development Project will focus on two key areas: 1) organizing the existing contributor docs, 2) creating new contributor docs based on research.
This project aims to improve the contributor docs section on p5.js GitHub repository to make it easier for new people to contribute, especially those without deep experience coding or contributing to open source. There currently are different types of contributor docs in the p5.js GitHub repository and p5.js Website GitHub repository, like access statement, project note, roadmap docs, etc. It can be difficult for contributors to navigate the existing contributor doc structure in the two repositories. A clearer organization structure will be beneficial for contributors who seek supporting documentation.
In addition to organizing and modifying the current documentation, this project will also include researching, proposing, and implementing new contributor docs for new use cases, like a translation guide for contributors who are interested in translating the p5.js website and documentation.
How did you come up with your Season of Docs proposal? What process did your organization use to decide on an idea? How did you solicit and incorporate feedback?
Our organization created our proposal by looking at our existing documentation through the lens of access. In what ways could our documentation afford greater access to contributing and working on the p5.js project? The p5.js project lead Qianqian Ye and our Executive Director Dorothy Santos worked collaboratively to answer this question. We framed the proposal into two key focus areas: 1) organizing the existing contributor docs, 2) creating new contributor docs based on research, leaving space for our technical writers to further shape the project with their own perspectives.
Include a short section on your budget. How did you estimate the work? Were there any unexpected expenses? Did you end up spending less than the grant award? Did you have other funds outside of Season of Docs that you were able to use?
Our project stayed within our $15,000 grant budget. We paid the technical writer $13,000 total, a $1,000 monthly stipend for contributions, based on an estimated 5-10 hours of work per week. We also paid 2 mentors $1,000 each for their support. In the future we would like to increase stipends for both mentors and technical writers to more closely match time and effort spent on projects.
The Processing Foundation did use internal funds (from donations and other grant awards) to cover administrative costs for the p5.js project leads throughout the Season of Docs project.
| Budget Item | Amount | Running Total | Notes |
|
Technical Writer -
p5.js Contributor Docs Organization & Development |
$13,000 | $13,000 | The technical writer will improve contributor docs, research and implement new community practices for beginning users. |
| Mentor Stipends | $1,000 x 2 | $15,000 | 2 mentors x $1,000 each |
| TOTAL | $15,000 |
Who worked on this project (use usernames if requested by participants)? How did you find and hire your technical writer? How did you find other volunteers or paid participants? What roles did they have? Did anyone drop out? What did you learn about recruiting, communication, and project management?
After receiving the grant from Google, we hired Kenneth Lim as the technical writer. Kenneth has been an active contributor to p5.js codebase, p5.js website, p5.js translation documentations, and was also a mentor for Season of Docs in 2021.
We decided to have two mentors for the writer to give feedback: Dr Peaks Krafft, Louis McCallum. Mentors were meant to be available to provide more frequent feedback, guidance, and other support than the project leads. We made sure that each mentor pair had experiences or skills relevant to the writer’s project, and had relationships with contributors in other parts of the p5.js community.
Give a short overview of the timeline of your project (indicate estimated end date or intermediate milestones if project is ongoing).
Our technical writer Kenneth Lim kicked off the project in June, and we had monthly check-ins with the writer to discuss progress, challenges, and questions. We used the first month for the technical writer to define his own timelines and work deliverables within the general headings provided in our project description. After that, Kenneth operated on his own timelines with support from his mentors.
| Task | Completed By |
| Technical writer hired | May 11 |
| First meeting with mentor | June 21 |
| Identify and analyze existing contributor docs | July 15 |
| Add additional contributor docs | September 8 |
| Edit existing contributor docs | October 9 |
| p5.js Contributor Survey created, translated and proofread | November 7 |
| P5.js Contributor Survey launched | November 9 |
| This case study created | November 1 |
| Case study submitted | November 28 |
What was created, updated, or otherwise changed? Include links to published documentation if available. Were there any deliverables in the proposal that did not get created? List those as well.
Contributor Doc Improvements
One problem that was identified early in the project was that the contributor documentations were spread out in many places including files committed into the git repo, GitHub wiki, README.md files, and many different pages on the official p5js.org website.
To rethink the possible structure for a beginner friendly contributor documentation, we decided to consolidate important information and clear step by step instructions into a single document that is clearly signposted. The user journey we aim to achieve is for beginner contributors to be pointed to the README.md page for the contributor docs, be provided overall information about the project’s community, design, and development philosophies, before they are guided to the comprehensive documentation that guides them from creating a new issue, discussing the issue with the community, working on a fix, submitting a PR, and getting the PR merged.
The goal here is for the single contributor_guidelines.md document to be the main touch point for new contributors to refer back to if needed for all essential information they need for contributing on GitHub. Additional files in the contributor docs folder are only used in the case of documenting specific optional sub-areas such as creating add-on libraries or working on the p5.js Friendly Error System.
We hope this new structure will provide clarity for new contributors about where they can find information about contribution and ease the anxieties that may come with contributing their very first contribution to open source.
P5.js Contributor Survey
To better understand the barriers contributors face when trying to contribute to p5.js, we have planned and started running a p5.js contributor survey in order to collect qualitative and quantitative data about our contributors’ experience.
The survey questions are mainly based on findings from existing literature and research by Igor Steinmacher, Gerado Canfora et al, and others looking into the field of software documentation and contributor experience in open source. Our goal is to use the same set of criterias (in terms of barriers to contribution) identified in the studies to determine where p5.js may be lacking when it comes to contributor experience. The result of which will inform the next steps the community can take in order to further improve our contributor experience especially for new contributors.
Further Documentation and Reflection
p5.js overall is a sizable project with many different components each all requiring some degree of contributor documentation in order to make sure they are sufficiently maintained. This posed a degree of difficulty in how a GSoD project can balance depth and width when deciding how to reorganize and rewrite which parts of all information required to contribute to p5.js.
While much effort was made to create a one-stop experience for new contributors in order for them to be onboarded with the contribution process with as little friction as possible, there are still many other areas that we can still apply the same kind of attention to, for example the p5.js website codebase would require its own set of setup instruction documentation.
The result of the contributor survey mentioned above should also be used as a basis of how we decide as a community where we prioritize effort in making contributions to p5.js easier and more accessible going forward.
Relevant PRs and new Contributor Docs pages
- https://github.com/processing/p5.js/pull/5764
- https://github.com/processing/p5.js/pull/5792
- https://github.com/processing/p5.js/pull/5813
- https://github.com/processing/p5.js/blob/main/contributor_docs/contributor_guidelines.md
- https://github.com/processing/p5.js/blob/main/contributor_docs/steward_guidelines.md
What metrics did you choose to measure the success of the project? Were you able to collect those metrics? Did the metrics correlate well or poorly with the outcomes you wanted for the project? Did your metrics change since your proposal?
We didn’t include quantitative metrics in the proposal for our projects. We would hope to see more issues files and pull requests opened from first-time contributors in the p5.js GitHub repo.
One element that we implemented as part of the restructuring of the contributor documentation is the creation of the steward guidelines document that is aimed specifically at maintainers and area stewards of p5.js. Stewards are a new system we recently implemented in which a community member volunteers to help with managing, responding, and providing advice on specific areas in the p5.js library. We created a steward guidelines as part of the contributor docs to provide both technical instructions on how to work with reviewing issues and PR but also information about how we aim to manage community contributions as a whole. This includes principles that are aligned with p5.js pledge of not accepting new features without a case made for how said new feature increases access.
What went well? What was unexpected? What hurdles or setbacks did you face? Do you consider your project successful? Why or why not? (If it's too early to tell, explain when you expect to be able to judge the success of your project.)
We consider our project successful thanks to the thoughtful and excellent work of our writer and mentors. The documentation is clear and helpful, and changes how we think about the p5.js project as a whole.
One unexpected hurdle we faced was the overall scope and amount of existing documentations that exist in many places such as in files committed in the repository, as comments in code files, as wiki pages, or as entries on many different pages on the website. The particular challenge was figuring out where relevant information for contributors were located and what information remained relevant while others were either duplicates or no longer applicable. By focusing on the journey a new contributor will need to take and removing information not immediately required by a new contributor, we were able to start the process of organizing and consolidating all the disparate pieces of information we have.
In 2-4 paragraphs, summarize your project experience. Highlight what you learned, and what you would choose to do differently in the future. What advice would you give to other projects trying to solve a similar problem with documentation?
We are proud of the work our writer has done to make p5.js more accessible to contributors and grateful to all the members of the community that supported their work. The project improved and expanded our understanding of our documentation and generated new excitement around in many areas of p5.js. We are excited to see the continued impact of the work on the contributor docs.
For other projects looking for advice, we would suggest:
- Jumpstart your technical writers’ connections with the community. Proactively connecting them with people who have worked in the areas they are writing about will not only give them early access to information but also help the project grow in ways you wouldn’t anticipate.
- Be intentional with the size of groups involved at different stages of your projects when synchronous meetings are needed. Consider other ways to create connections between writers, collaborators, and other community members.
- Account for ambiguity in your projects in your timeline. Regardless of the level of experience your writers have, they won’t have all the context you do (and you don’t have all the context they’ll need either!). Consider how to structure time for them to find and resolve ambiguity in the project definition, whether it happens all upfront, periodically, or something else.
If you have other materials you'd like to link to (for example, if you created a contract for working with your technical writer that you'd like to share, or templates for your documentation project, or other open documentation resources, you can list and link them here). The Appendix is also a good place to list links to any documentation tools or resources you used, or a place to add thanks or acknowledgments that might not fit into the sections above.
Aghajani, E., Nagy, C., Vega-Márquez, O.L., Linares-Vásquez, M., Moreno, L., Bavota, G., Lanza, M., 2019. Software Documentation Issues Unveiled, in: 2019 IEEE/ACM 41st International Conference on Software Engineering (ICSE). Presented at the 2019 IEEE/ACM 41st International Conference on Software Engineering (ICSE), pp. 1199–1210.[ https://doi.org/10.1109/ICSE.2019.00122](https://doi.org/10.1109/ICSE.2019.00122)
Aversano, L., Guardabascio, D., Tortorella, M., 2017. Evaluating the Quality of the Documentation of Open Source Software:, in: Proceedings of the 12th International Conference on Evaluation of Novel Approaches to Software Engineering. Presented at the 12th International Conference on Evaluation of Novel Approaches to Software Engineering, SCITEPRESS - Science and Technology Publications, Porto, Portugal, pp. 308–313.[ https://doi.org/10.5220/0006369403080313](https://doi.org/10.5220/0006369403080313)
Canfora, G., Di Penta, M., Oliveto, R., Panichella, S., 2012. Who is going to mentor newcomers in open source projects?, in: Proceedings of the ACM SIGSOFT 20th International Symposium on the Foundations of Software Engineering - FSE ’12. Presented at the the ACM SIGSOFT 20th International Symposium, ACM Press, Cary, North Carolina, p. 1.[ https://doi.org/10.1145/2393596.2393647](https://doi.org/10.1145/2393596.2393647)
Forward, A., Lethbridge, T.C., 2002. The relevance of software documentation, tools and technologies: a survey, in: Proceedings of the 2002 ACM Symposium on Document Engineering - DocEng ’02. Presented at the the 2002 ACM symposium, ACM Press, McLean, Virginia, USA, p. 26.[ https://doi.org/10.1145/585058.585065](https://doi.org/10.1145/585058.585065)
Steinmacher, I., Conte, T., Gerosa, M.A., Redmiles, D., 2015a. Social Barriers Faced by Newcomers Placing Their First Contribution in Open Source Software Projects, in: Proceedings of the 18th ACM Conference on Computer Supported Cooperative Work & Social Computing. Presented at the CSCW ’15: Computer Supported Cooperative Work and Social Computing, ACM, Vancouver BC Canada, pp. 1379–1392.[ https://doi.org/10.1145/2675133.2675215](https://doi.org/10.1145/2675133.2675215)
Steinmacher, I., Conte, T.U., Treude, C., Gerosa, M.A., 2016. Overcoming open source project entry barriers with a portal for newcomers, in: Proceedings of the 38th International Conference on Software Engineering. Presented at the ICSE ’16: 38th International Conference on Software Engineering, ACM, Austin Texas, pp. 273–284.[ https://doi.org/10.1145/2884781.2884806](https://doi.org/10.1145/2884781.2884806)
Steinmacher, I., Graciotto Silva, M.A., Gerosa, M.A., Redmiles, D.F., 2015b. A systematic literature review on the barriers faced by newcomers to open source software projects. Information and Software Technology 59, 67–85.[ https://doi.org/10.1016/j.infsof.2014.11.001](https://doi.org/10.1016/j.infsof.2014.11.001)
Uddin, G., Robillard, M.P., 2015. How API Documentation Fails. IEEE Software 32, 68–75.[ https://doi.org/10.1109/MS.2014.80](https://doi.org/10.1109/MS.2014.80)
Watson, R., Mark Stamnes, M., Jeannot-Schroeder, J., Spyridakis, J.H., 2013. API documentation and software community values: a survey of open-source API documentation, in: Proceedings of the 31st ACM International Conference on Design of Communication - SIGDOC ’13. Presented at the the 31st ACM international conference, ACM Press, Greenville, North Carolina, USA, p. 165.[ https://doi.org/10.1145/2507065.2507076](https://doi.org/10.1145/2507065.2507076)
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.