pyOpenSci’s Content Development Process#

pyOpenSci develops and maintains several online resources, including:

a Python packaging guidebook that provides recommendations and best practices for creating and sharing Python code.
online lessons teach scientists critical open science skills including packaging, writing cleaner code, sharing code and collaborating on Github and making their work open and citable.

A core value of pyOpenSci is making science more inclusive by ensuring our content is accessible and beginner-friendly. This commitment allows more people to participate in science.

To uphold this value, pyOpenSci has developed a review process to ensure that all of its online content is:

Accurate
Accessible, and
Beginner-friendly.

This page overviews that process, which applies to all technical content and lessons created for the pyOpenSci website.

Flowchart illustrating the pyOpenSci content review process. The process starts with 'Expert Feedback,' followed by 'Community Review (2 rounds),' then moves to 'Sprints / Bug Bashes,' and concludes with a 'Living Document' represented by a growing vine with leaves and flowers. — pyOpenSci has a review process that ensures that all the content published online is technically accurate and accessible to those who are new to the topic.#

Roles and Responsibilities#

Several “types” of contributors are critical to achieving the pyOpenScis content goals.

Content Authors: Write early drafts with research to ensure accuracy. Engage with content experts for initial reviews. Content authors are often but not always pyOpenSci staff or a part of the pyOpenSci core contributor teams.
Content Experts: Provide early feedback on drafts to ensure technical accuracy. This feedback is most often provided online, ideally on GitHub, but sometimes via Slack or Discord. This feedback ensures the initial drafts capture important topics and concepts accurately.
Community Reviewers: Participate in the GitHub pull request review process, providing feedback within the designated review period. Generally, the Pull Request associated with the new content will be provided as a link to the community in Slack and left open for review for a specific period of time.
Moderators: Oversee the review process, manage conflicts, and ensure that the final content meets pyOpenSci accessibility and accuracy standards.
Decision-Makers: Facilitate consensus and make final decisions on content approval. Typically, the Executive Director of pyOpenSci makes final decisions when consensus can’t be reached. However, more often, the community is able to achieve consensus and merge content.

Where reviews happen#

Content reviews most often occur on GitHub through the standard Pull Request review process; however, in some instances raw content is generated first in a platform such as Google Docs or HackMD.

Review timelines vary but often range between 1-2 weeks for new content. Reviewers are encouraged to provide feedback on clarity, accuracy, and accessibility. Once a review is complete, the pull request authors document and address all review comments, and the pull request is merged.

When possible, pyOpenSci aims for a rapid iteration of content where we merge more quickly, pilot the materials in online events and make updates based on feedback rather than long iterative review processes around a single pull request.

In some cases, we will have multiple rounds of review for individual content sections.

Conflicts of interest around tools

If we are teaching new tools, it is important that content participants in the review process disclose any potential conflicts of interest, including tools that they actively maintain, contribute to or have authored.