feat(process): add content development process to the handbook

Author: lwasser

community/content-development-process.md

@@ -0,0 +1,55 @@
+# pyOpenSci's Content Development Process
+
+pyOpenSci develops and maintains several online resources, including:
+
+* a [Python packaging guidebook](https://www.pyopensci.org/python-package-guide/) that provides
+recommendations and best practices for creating and sharing Python code.
+* [online lessons](https://www.pyopensci.org/lessons) teach scientists critical open science skills including packaging, [writing cleaner code](https://www.pyopensci.org/lessons/clean-modular-code/intro-clean-code.html#intro-clean-code), [sharing code](https://www.pyopensci.org/lessons/publish-share-code/intro.html) and [collaborating on Github](https://www.pyopensci.org/lessons/github-git/intro.html) and making their work open and [citable](https://www.pyopensci.org/lessons/publish-share-code/cite-code.html).
+
+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.
+
+
+:::{figure} /images/guidebook-living-document.png
+:alt: 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](https://github.com/orgs/pyOpenSci/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.
+
+
+:::{admonition} 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.
+:::

community/index.md

@@ -13,7 +13,7 @@ scientific Python community.
 
 :::{toctree}
 :maxdepth: 2
-:caption: Social Media
+:caption: Community Platforms & Channels
 
 Social Media <social>
 Slack <slack>
@@ -34,8 +34,9 @@ GitHub permissions <github/permissions>
 
 :::{toctree}
 :maxdepth: 2
-:caption: pyOpenSci Events
+:caption: Events & Content Development
 
 Events <events/intro>
 pyOpenSci Sprints <events/sprints>
+Content Development <content-development-process>
 :::

conf.py

@@ -1,27 +1,12 @@
 # Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
 # -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
 from datetime import datetime
 import subprocess
 
 current_year = datetime.now().year
 organization_name = "pyOpenSci"
 
 # -- Project information -----------------------------------------------------
-
 project = "pyOpenSci Handbook"
 copyright = f"{current_year}, {organization_name}"
 author = "pyOpenSci"
@@ -107,7 +92,7 @@
     "navigation_depth": 3,
     "show_toc_level": 1,
     # "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
-    "github_url": "https://github.com/pyopensci/governance",
+    "github_url": "https://github.com/pyopensci/handbook",
     "footer_start": ["copyright"],
     "footer_end": [],
 }
@@ -118,14 +103,14 @@
 
 html_context = {
     "github_user": "pyopensci",
-    "github_repo": "governance",
+    "github_repo": "handbook",
     "github_version": "main",
 }
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
-# List of patterns, relative to source directory, that match files and
+# List of patterns relative to source directory that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = [
@@ -139,7 +124,7 @@
 ]
 
 # For sitemap generation
-html_baseurl = "https://www.pyopensci.org/governance/"
+html_baseurl = "https://www.pyopensci.org/handbook/"
 sitemap_url_scheme = "{link}"
 
 # -- Options for HTML output -------------------------------------------------
@@ -149,13 +134,13 @@
 html_js_files = ["matomo.js"]
 
 
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
+# Add paths containing custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the built-in static files,
+# so a file named "default.css" will overwrite the built-in "default.css".
 html_static_path = ["_static"]
 
 # Social cards
-ogp_site_url = "https://www.pyopensci.org/governance/"
+ogp_site_url = "https://www.pyopensci.org/handbook/"
 ogp_social_cards = {
     "line_color": "#6D597A",
     "image": "_static/logo-dark-mode.png",

governance/index.md

@@ -1,6 +1,7 @@
 # Governance, Structure & Values
 
 ## About
+
 pyOpenSci is a fiscally sponsored nonprofit organization whose mission is to build diverse,
 supportive community around the free and open Python tools that drive open
 science.
@@ -11,7 +12,6 @@ pyOpenSci supports open science through
 * **Mentorship:** We will build out a community program where diverse community members are mentored in skills needed to contribute to open source software, which in turn will propel their open science skills forward.
 * **Training:** pyOpenSci will provide training in skills needed to contribute to open source software.
 
-
 ```{toctree}
 :hidden:
 :caption: Organization Structure
@@ -22,7 +22,6 @@ structure
 Code of Conduct <../CODE_OF_CONDUCT.md>
 ```
 
-
 ```{toctree}
 :hidden:
 :caption: Reference Information

governance/structure.md

@@ -109,7 +109,7 @@ The editors oversee 3-4 packages a year.
 
 The Editor in Chief role is a rotating position
 that is held by someone on the editorial board. [More on this position can be
-found in the contributing guide here.](https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html).
+found in the pyOpenSci software peer review guide here.](https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html)
 
 ### Volunteer reviewers