From 757708a390cd4a7144186e0f4bb03056f2a3a5e4 Mon Sep 17 00:00:00 2001 From: mariatta Date: Tue, 9 Jun 2026 15:58:22 -0700 Subject: [PATCH 1/2] Add Board Roles and Projects pages Following the June 2026 meeting, the board adopted a proactive stance: identify significant documentation projects and lead/shepherd them, rather than only reacting to escalations (while remaining available for the rare big-picture decisions). Add two draft pages and link them in the nav: - /expectations (Board Roles): purpose, the chosen proactive stance, member expectations, and the PEP 732 process for joining. - /projects: rules (every project needs a committed lead; name the challenges; keep the list short), a copy-paste project template, and a parking lot for lead-less ideas. Co-Authored-By: Claude Opus 4.8 (1M context) --- content/expectations.md | 91 +++++++++++++++++++++++++++++++++++++++++ content/projects.md | 84 +++++++++++++++++++++++++++++++++++++ hugo.yaml | 8 ++++ 3 files changed, 183 insertions(+) create mode 100644 content/expectations.md create mode 100644 content/projects.md diff --git a/content/expectations.md b/content/expectations.md new file mode 100644 index 0000000..e2a6d4d --- /dev/null +++ b/content/expectations.md @@ -0,0 +1,91 @@ +--- +title: "Board Expectations & Roles" +url: "/expectations" +summary: "What we expect of Editorial Board members, and how the board operates." +hideMeta: true +ShowToc: true +TocOpen: true +--- + +> **Status: Draft.** This page is a work in progress, started following the +> [June 2026 meeting](/updates/2026-06-09/). It describes what we expect of +> Editorial Board members and how the board chooses to operate. Comments and +> suggestions are welcome via an [issue](https://github.com/python/editorial-board/issues/new/choose). + +## Purpose + +The Python Documentation Editorial Board exists to maintain and improve the +quality of Python's documentation, as established in +[PEP 732](https://peps.python.org/pep-0732/). PEP 732 defines our mandate, +scope, responsibilities, and membership rules; this page does not restate the +PEP but instead records how the board chooses to work within it. + +## How we work: proactive, not just reactive + +The board considered three possible stances for how members spend their time: + +1. **Reactive** — be available to make big decisions when asked (act like a + "Steering Council for docs"). +2. **Hands-on** — start and personally carry out significant work (closer to a + core-team contributor role than a council role). +3. **Proactive** — identify big documentation projects, reach out to find + people to do the work, and lead/shepherd those efforts. + +**We have chosen stance 3.** Rather than waiting for issues to be escalated to +us, the board will actively identify significant documentation work, find and +support contributors to take it on, and project-manage those efforts to +completion. + +We remain available for the reactive decision-making in stance 1 — when the +community needs the board to make a big-picture or tie-breaking decision about +the docs, we are here to do so. In practice, though, this has rarely been +needed: most documentation questions resolve without the board having to step +in. Because that reactive load is light, our primary focus is the proactive +work described above. + +What this means in practice: + +- We maintain a [list of projects](/projects/) that we believe are worth doing. +- A project is listed **only if there is a committed lead** for it. The list is + not a wish list — every entry has someone accountable for moving it forward. +- Each project is described with enough detail to be actionable, including the + challenges and risks involved, not just the desired outcome. +- We hold ourselves to project-managing these efforts, not merely naming them. + +## Member expectations + +Members of the Editorial Board are expected to: + +- Attend the monthly board meeting (second Tuesday, 1:30pm Pacific) where + possible, and stay engaged asynchronously on Discord between meetings. +- Help identify and prioritize documentation projects. +- Lead or actively shepherd at least one project, or support fellow members + who are leading projects. +- Engage constructively with the wider documentation community (the + [Documentation Working Group](https://github.com/python/docs-community), + translation teams, and contributors). +- Confirm annually whether they wish to continue serving, per PEP 732. + +### What it means to lead a project + +_TODO: define the commitment expected of a project lead — e.g. defining scope, +breaking the work into contributable pieces, recruiting and supporting +contributors, reporting progress to the board, and seeing the work through._ + +## Joining the board + +The process for filling a vacancy is defined in PEP 732 under +[Editorial Board Member Qualifications](https://peps.python.org/pep-0732/#editorial-board-member-qualifications): + +> If a vacancy exists on the board for any reason, the Documentation Editorial +> Board will publicly announce a call for prospective board members. +> Prospective board members would submit a brief document stating +> qualifications and their motivation to serve. The sitting members of the +> Editorial Board will select new board members by a simple majority where +> quorum is 80% of the current board. + +Before opening a call for new members, the board will publish clear +expectations (this page) so prospective members understand what they are +signing up for. + +_TODO: link to the application form / call for members once it is open._ \ No newline at end of file diff --git a/content/projects.md b/content/projects.md new file mode 100644 index 0000000..981b79d --- /dev/null +++ b/content/projects.md @@ -0,0 +1,84 @@ +--- +title: "Projects" +url: "/projects" +summary: "Documentation projects the Editorial Board is leading or shepherding." +hideMeta: true +ShowToc: true +TocOpen: true +--- + +> **Status: Draft.** This page is a work in progress, started following the +> [June 2026 meeting](/updates/2026-06-09/). + +This is the Editorial Board's list of significant documentation projects we are +actively leading or shepherding. It reflects our +[proactive stance](/expectations/#how-we-work-proactive-not-just-reactive): +rather than only reacting to requests, we identify important work and find +people to carry it out. + +## How this list works + +- **Every project has a committed lead.** This is not a wish list. A project is + added only when someone has agreed to lead it. If a project loses its lead, it + moves to [Parking lot](#parking-lot) until a new lead steps up. +- **Each project names its challenges**, not just the goal. Describing the + hard parts up front helps contributors know what they are taking on. +- **We keep the list short and prioritized** rather than long and + aspirational, so we can give each project real oversight. + +Want to help with a project, or propose a new one? Open an +[issue on this repo](https://github.com/python/editorial-board/issues/new/choose) +or reach out on [Discord](https://discord.gg/nXkJ2JYvCu). + +## Project template + +Copy this block to add a new project. + +```markdown +### + +- **Lead:** +- **Status:** Proposed | Active | Blocked | Done +- **Summary:** One or two sentences on what this project delivers. +- **Why it matters:** Who benefits and why this is worth doing now. +- **Challenges / risks:** The hard parts — technical blockers, dependencies, + unknowns, things that could derail it. +- **How to help:** Concrete ways a contributor can get involved. +- **Links:** Relevant issues, PRs, discussions, or docs. +``` + +## Active projects + +_None listed yet. Add projects here using the template above._ + + + +## Parking lot + +Ideas worth doing that do **not** yet have a committed lead. These are not +active projects until someone steps up to lead them. + +_Empty for now._ \ No newline at end of file diff --git a/hugo.yaml b/hugo.yaml index 38d6239..3fa76db 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -77,6 +77,14 @@ menu: name: Changelog url: /changelog weight: 30 + - identifier: projects + name: Projects + url: /projects + weight: 35 + - identifier: expectations + name: Board Roles + url: /expectations + weight: 37 - identifier: archives name: Archives url: /archives From ad998cdea60c5edc2c96520f75dcbea89219ce34 Mon Sep 17 00:00:00 2001 From: Mariatta Date: Thu, 11 Jun 2026 15:41:24 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Ned Batchelder --- content/expectations.md | 2 +- content/projects.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/expectations.md b/content/expectations.md index e2a6d4d..703c3f6 100644 --- a/content/expectations.md +++ b/content/expectations.md @@ -31,7 +31,7 @@ The board considered three possible stances for how members spend their time: 3. **Proactive** — identify big documentation projects, reach out to find people to do the work, and lead/shepherd those efforts. -**We have chosen stance 3.** Rather than waiting for issues to be escalated to +**We have chosen to focus on stance 3.** Rather than waiting for issues to be escalated to us, the board will actively identify significant documentation work, find and support contributors to take it on, and project-manage those efforts to completion. diff --git a/content/projects.md b/content/projects.md index 981b79d..bbc78c1 100644 --- a/content/projects.md +++ b/content/projects.md @@ -28,11 +28,11 @@ people to carry it out. Want to help with a project, or propose a new one? Open an [issue on this repo](https://github.com/python/editorial-board/issues/new/choose) -or reach out on [Discord](https://discord.gg/nXkJ2JYvCu). +or reach out in the [Python Docs Discord](https://discord.gg/nXkJ2JYvCu). ## Project template -Copy this block to add a new project. +Once a project is approved by the Editorial Board, copy this block to add a new project. ```markdown ###