Google Season of Docs 2023: NumPy case study
It can be difficult for contributors to navigate a vast opensource project like NumPy. There are multiple pathways of contribution and all of them equally valuable. Our aim through the NumPy comics was to introduce one such pathway in a way approachable to contributors new to opensource and NumPy alike. The complete proposal can be found at Google Season of Docs 2023: Project Proposal.
NumPy maintainers are often posed with the question "How can I contribute?" or "Where do I start?" at community meetings and discussion forums. While our documentation is fairly complete with respect to the project's needs and expectations, it can be quite verbose and not an appealing read. This made us recognize the need for an alternate and effective medium for getting this information across. Based on previous works, community member Mars suggested the idea for using comics as our desired medium and some initial ideation work was done in 2022. It shaped up to be a well-contained project that the community felt was worth pursuing. Mars formulated the project proposal and iterated with community members at multiple NumPy community meetings.
As we already had our technical writer in mind, we requested a budget according to her pay rate for part-time work for six months. In the end, the project came out to be slightly over budget as there was a slight expansion in the timeline. We were not funded by any other organization for this project.
As Mars (@MarsBarLee) was heavily involved in the conceptualization of the project and showed a clear understanding of how to proceed, she was picked as the technical writer. She also submitted a project roadmap with detailed plans. The project mentors (@Mukulikaa and @rossbar) volunteered their time at the project formulation stage. There was regular communication between both parties with updates about project progress, challenges and other needs. The technical writer's efforts to sync with the mentors and community members allowed everyone to be a part of the project and established a good feedback mechanism.
The timeline was fairly consistent with the original plan except for a slight restructuring of goals that has expanded the timeline by a few weeks. The timeline we followed:
- Gathering community input for project plans (May 1 - 15)
- Outlining stage (May 15-26)
- Review #1 (late May-early June)
- Scriptwriting stage (July - early August)
- Review #2 (mid-August)
- Illustrating stage (September-October)
The next steps are:
- Completing illustrations
- Review #3
- Publishing on the documentation website
The project resulted in a digital comic- How to Contribute to NumPy, soon to be hosted on the NumPy website. It also led to a talk (Comics in NumPy? More Likely than You Think!) at PyData NYC 2023; the recording for which will be publicly available in January 2024. Around a hundred physical copies of the comics were handed to participants of the conference. The complete source materials for the comics and the talk can be found at this Git repository.
The metrics we set out were:
- Increase in first-time attendees to the NumPy community meetings
- Increase in first-time contributors becoming repeating contributors
- Increase in the number of responses to issues by non-maintainers
- Increase in the number of reviews made by non-maintainers
- Increase in the number of people given repository rights
Most of these metrics will be measured over the coming months as we incorporate the comics as part of our official documentation and get more readership. We can detect a positive trend in the fourth metric through the high-level discussions sparked by this project in the community. We received a lot of comments and reviews during the development of the comics based on personal contribution journeys and backgrounds. We see this as an indicator of upcoming success in the other metrics too.
This was a successful project for the value it provided to the organization. There were many fruitful discussions around contributor journeys and documentation needs which have given the community more direction to improve the documentation in future projects. It was also interesting to see how graphics can be incorporated into documentation work and the challenges that come with it in reviewing such work. We experimented with different review channels like GitHub, Google Docs, and Notion and found pros and cons in each of them. The direct impact of the comics can be analyzed soon, as we start measuring our metrics.
This project provided a viable solution to a clear problem we are facing in our documentation. We were fortunate to have a technical writer with such clear motivation and artistic vision. The technical writer also provided us with a peek at the artistic process behind making graphics for technical concepts.
It was a novel undertaking for NumPy and it worked out very well. We wish to monitor the effects of this work on new contributions to the organization and expand on this work as required. We hope this will inspire other organizations to explore and adopt different mediums in their documentation too.
Other instances of graphics in technical documentation: