With an extensive and high-quality ecosystem of libraries, scientific Python has emerged as the leading platform for data analysis. This ecosystem is sustained largely by volunteers working on independent projects with separate mailing lists, websites, roadmaps, documentation, engineering and packaging solutions, and governance structures.
The Scientific Python project aims to better coordinate the ecosystem and prepare the software projects in this ecosystem for the next decade of data science.
There is no shortage of blog posts around the web about how to use and explore different packages in the scientific Python ecosystem. However, some of it is outdated or incomplete, and many times doesn’t follow the best practices that would be advocated for by the maintainers of these packages.
In addition, we would like to create a central, community-driven location where Scientific Python projects can make announcements and share information.
Our project aims to be the definitive community blog—for people looking to make use of these libraries in education, research and industry, contribute to them, or maintain them—written, reviewed, and approved by the community of developers and users.
While our core projects (NumPy, SciPy, Matplotlib, scikit-image, NetworkX, etc.) will be regularly contributing content, we also would like to increase the number of contributors by providing support to newer members to generate high-quality, peer-reviewed blog posts.
Our goal is to populate the https://blog.scientific-python.org/ website with high-quality content, reviewed and approved by the maintainers of the libraries in the ecosystem. The main goal of these documents is to centralize information relevant to all (or most) projects in the ecosystem, at the reduced cost of being maintained in one place.
This project aims to:
To ensure this project is successful, it is recommended that the technical writer has some familiarity with at least a few of Scientific Python’s core projects.
We would consider the project successful if:
We anticipate the project to be developed over six months including onboarding five technical writers, reviewing existing material, developing blog post ideas with the project mentors and blog editorial board, writing and revising the blog posts, as well as providing feedback on the submission and review process.
| Dates | Action Items |
|---|---|
| May | Onboarding |
| June | Review existing documentation |
| July | Update contributor guide |
| August–October | Create and edit content |
| November | Project completion |
| Budget item | Amount | Running Total | Notes/justifications |
|---|---|---|---|
| Technical writers (5) | $15,000.00 | $15,000.00 | $3,000 / writer |
| TOTAL | $15,000.00 |
The Scientific Python project is a new initiative, and this is our first time participating in Google Season of Docs. However, both Jarrod Millman and Ross Barnowski are established members of the Python community, with a vast collective experience in mentoring, managing and maintaining large open source projects.
Jarrod cofounded the Neuroimaging in Python project. He was the NumPy and SciPy release manager from 2007 to 2009. He cofounded NumFOCUS and served on its board from 2011 to 2015. Currently, he is the release manager of NetworkX and cofounder of the Scientific Python project.
Both mentors Jarrod and Ross have mentored many new contributors on multiple projects including NumPy, SciPy, and NetworkX. Ross has served as a co-mentor for three former GSoD students on the NumPy project, largely related to generating new content for tutorials, as well as refactoring existing user documentation.
Links:
]]>This year’s Google Season of Docs (GSoD) provided me the opportunity to work with the open source organization, Matplotlib. In early summer, I submitted my proposal of Developing Matplotlib Entry Paths with the goal of improving the documentation with an alternative approach to writing.
I had set out to identify with users more by providing real world contexts to examples and programming. My purpose was to lower the barrier of entry for others to begin using the Python library with an expository approach. I focused on aligning with users based on consistent derived purposes and a foundation of task-based empathy.
The project began during the community bonding phase with learning the fundamentals of building documentation and working with open source code. I later generated usability testing surveys to the community and consolidated findings. From these results, I developed two new documents for merging into the Matplotlib repository, a Getting Started introductory tutorial and a lean Style Guide for the documentation.
Throughout this year’s Season of Docs with Matplotlib, I learned a great deal about working on open source projects, provided contributions of surveying communities and interviewing subject matter experts in documentation usability testing, and produced a comprehensive introductory guide for improving entry-level content with an initiative style guide section.
As a new user to Git and GitHub, I had a learning curve in getting started with building documentation locally on my machine. Working with cloning repositories and familiarizing myself with commits and pull requests took the bulk of the first few weeks on this project. However, with experiencing errors and troubleshooting broken branches, it was excellent to be able to lean on my mentors for resolving these issues. Platforms like Gitter, Zoom, and HackMD were key in keeping communication timely and concise. I was fortunate to be able to get in touch with the team to help me as soon as I had problems.
With programming, I was not a completely fresh face to Python and Matplotlib. However, installing the library from the source and breaking down functionality to core essentials helped me grow in my understanding of not only the fundamentals, but also the terminology. Tackling everything through my own experience of using Python and then also having suggestions and advice from the development team accelerated the ideas and implementations I aimed to work towards.
New formats and standards with reStructuredText files and Sphinx compatibility were unfamiliar avenues to me at first. In building documentation and reading through already written content, I adapted to making the most of the features available with the ideas I had for writing material suited for users new to Matplotlib. Making use of tables and code examples embedded allowed me to be more flexible in visual layout and navigation.
During the beginning stages of the project, I was able to incorporate usability testing for the current documentation. By reaching out to communities on Twitter, Reddit, and various Slack channels, I compiled and consolidated findings that helped shape the language and focus of new content to create. I summarized and shared the community’s responses in addition to separate informational interviews conducted with subject matter experts in my location. These data points helped in justifying and supporting decisions for the scope and direction of the language and content.
At the end of the project, I completed our agreed upon expectations for the documentation. The focused goal consisted of a Getting Started tutorial to introduce and give context to Matplotlib for new users. In addition, through the documentation as well as the meetings with the community, we acknowledged a missing element of a Style Guide. Though a comprehensive document for the entire library was out of the scope of the project, I put together, in conjunction with the featured task, a lean version that serves as a foundational resource for writing Matplotlib documentation.
The two sections are part of a current pull request to merge into Matplotlib’s repository. I have already worked through smaller changes to the content and am working with the community in moving forward with the process.
This Season of Docs proposal began as a vision of ideals I hoped to share and work towards with an organization and has become a technical writing experience full of growth and camaraderie. I am pleased with the progress I had made and cannot thank the team enough for the leadership and mentorship they provided. It is fulfilling and rewarding to both appreciate and be appreciated within a team.
In addition, the opportunity put together by the team at Google to foster collaboration among skilled contributors cannot be understated. Highlighting the accomplishments of these new teams raises the bar for the open source community.
Special thanks to Emily Hsu, Joe McEwen, and Smriti Singh for their time and responses, fellow Matplotlib Season of Docs writer Bruno Beltran for his insight and guidance, and the Matplotlib development team mentors Tim, Tom, and Hannah for their patience, support, and approachability for helping a new technical writer like me with my own Getting Started.
My name is Jerome Villegas and I’m a technical writer based in Seattle. I’ve been in education and education-adjacent fields for several years before transitioning to the industry of technical communication. My career has taken me to Taiwan to teach English and work in publishing, then to New York City to work in higher education, and back to Seattle where I worked at a private school.
Since leaving my job, I’ve taken to supporting my family while studying technical writing at the University of Washington and supplementing the knowledge with learning programming on the side. Along with a former classmate, the two of us have worked with the UX writing community in the Pacific Northwest. We host interview sessions, moderate sessions at conferences, and generate content analyzing trends and patterns in UX/tech writing.
In telling people what I’ve got going on in my life, you can find work I’ve done at my personal site and see what we’re up to at shift J. Thanks for reading!
]]>