Add Board Roles and Projects pages by Mariatta · Pull Request #41 · python/editorial-board

Mariatta · 2026-06-11T20:00:17Z

Summary

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). These two draft pages capture that direction and give us a place to track the work.

New pages

/expectations (nav: "Board Roles") — purpose (pointing to PEP 732 rather than restating it), the three stances considered and the chosen proactive one, member expectations, and the PEP 732 process for joining. Includes TODOs for defining the project-lead commitment and linking the eventual application form.
/projects — the operating rules (every project needs a committed lead; each names its challenges; keep the list short and prioritized), a copy-paste project template, an empty "Active projects" section with a commented-out datetime-split example seeded from recent meetings, and a "Parking lot" for lead-less ideas.

Both are marked Status: Draft at the top. They're linked in the top nav between Changelog and Archives.

Verification

hugo --gc --minify builds clean (71 pages, no errors); both pages render and appear in the nav.

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) <noreply@anthropic.com>

netlify · 2026-06-11T20:00:42Z

✅ Deploy Preview for pythoneditorialboard ready!

Name	Link
🔨 Latest commit	`ad998cd`
🔍 Latest deploy log	https://app.netlify.com/projects/pythoneditorialboard/deploys/6a2b39974012630008cc0948
😎 Deploy Preview	https://deploy-preview-41--pythoneditorialboard.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

hugovk · 2026-06-11T20:42:40Z

+- 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.


At the top: "this page does not restate the
PEP but instead records how the board chooses to work within it"

But this sentence is restating the PEP. Perhaps delete?

StanFromIreland · 2026-06-11T20:47:39Z

+
+- 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.


I think this contradicts the above, is it not the EB that is going to "lead/shepherd [these] efforts," or am I misunderstanding the above?

This is a good question. In our discussion, we meant that the EB members would lead projects themselves, but this sentence doesn't actually say that. I'm not sure we should require an EB member to be the lead. Whatever we decide, we should be clear. How about:

every entry has someone accountable for moving it forward. That will be an EB member or someone identified by the board.

Perhaps we should also say that someone from the EB will be associated with each active project, if only as an "executive sponsor" or something.

I also would agree that non EB members can be project lead and have an EB member to be a sponsor, and that there should also be regular checkins between the sponsoree and the EB sponsor.

I agree that it makes most sense that each project will have an EB member associated with it, either as a sponsor or a project lead.

StanFromIreland · 2026-06-11T21:50:15Z

+- **Summary:** Break the large `datetime` reference page into more focused
+  pages, and move the strftime/strptime format codes to their own page.
+- **Why it matters:** `datetime.rst` is among the ten largest files in the docs;
+  it mixes reference and tutorial-style content. More focused pages improve
+  navigation, SEO, and discoverability (including by LLMs).
+- **Challenges / risks:** Existing external links will break — depends on the
+  redirect mechanism being worked on in the Docs WG (Petr). Some readers value
+  a single page they can Ctrl-F (per feedback from Paul Ganssle). Needs
+  coordination with in-flight PRs (#125009, #132524) and with Stan.
+- **How to help:** Help define the page split, draft an overall tutorial,
+  separate reference from tutorial content.


Leaving this note here since there isn't an issue or other clear place to do it.

I've also been thinking about this for a while, especially with the recent update to the format codes.

and move the strftime/strptime format codes to their own page.

This is interesting, but it would disconnect them from their APIs, which I would find a little odd. However, the table also applies to time.stptime (and partially time.strftime) and a slightly dated copy is duplicated in the time module docs. I'm working on tidying this up soon.

mixes reference and tutorial-style content.

I think the current structure is reasonable: we introduce an object, cover its API in detail, and follow with a small cookbook

depends on the redirect mechanism being worked on in the Docs WG

I opened a PR for this: python/cpython#151113 :-)

draft an overall tutorial

I'm not sure a tutorial is the best use of our limited time. There are many tutorials on the internet already, I don't think an "official" one will be particularly special.

This is a great example of the kinds of difficult decisions that have to be made for projects that seem simple at first glance.

I'm a proponent of doing the work a few times and being thoughtful about the decisions being made along the way, then ideally codifying those decisions as guidelines that others can follow to make future changes easier.

nedbat · 2026-06-11T22:13:53Z

+
+- 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.


This is a good question. In our discussion, we meant that the EB members would lead projects themselves, but this sentence doesn't actually say that. I'm not sure we should require an EB member to be the lead. Whatever we decide, we should be clear. How about:

every entry has someone accountable for moving it forward. That will be an EB member or someone identified by the board.

Perhaps we should also say that someone from the EB will be associated with each active project, if only as an "executive sponsor" or something.

nedbat · 2026-06-11T22:14:37Z

+  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.


Here is where the EB member is described as the project lead. Whatever we decide above, this sentence needs to match.

nedbat · 2026-06-11T22:20:18Z

+
+_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._


Also: recognizing when a project isn't working out, and wrapping it up even though it wasn't done.

I would add these tasks to the beginning of the list of tasks owned by an EB member associated with a project:

Propose a potential project to the other EB members for approval

Scope the project and present the intended scope to the other EB members for approval

I'm thinking that someone could come up with an idea, come to a general consensus with the rest of the EB on the broad strokes, and then go off to make it happen with docs community members. After that, the EB member who owns the project could keep the rest of the EB in the loop or ask for input as issues arise.

nedbat · 2026-06-11T22:27:00Z

+
+- **Lead:** <name — required; no lead, no listing>
+- **Status:** Proposed | Active | Blocked | Done
+- **Summary:** One or two sentences on what this project delivers.


I don't see a reason to limit this to two sentences. Or leave this as-is, but also add a "Description" section that can be longer with as much detail as needed.

I like the idea of having both a short summary and a complete description. The short summary shows that there is a "there" there. The complete description lets contributors know what they're in for.

Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>

jablonskidev · 2026-06-27T00:27:13Z

+
+- 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.


I agree that it makes most sense that each project will have an EB member associated with it, either as a sponsor or a project lead.

jablonskidev · 2026-06-27T00:28:12Z

+
+**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


"and either sponsor or project-manage those efforts"

jablonskidev · 2026-06-27T00:33:53Z

+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


When we say that all listed projects must have a committed lead, do we mean that we require all listed projects to have a project manager or just an EB board member associated with it? I like the idea of only requiring listed projects to have an EB member committed to it. That way, potential project leads have something concrete to say yes to.

jablonskidev · 2026-06-27T00:44:18Z

+
+_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._


I would add these tasks to the beginning of the list of tasks owned by an EB member associated with a project:

Propose a potential project to the other EB members for approval

Scope the project and present the intended scope to the other EB members for approval

I'm thinking that someone could come up with an idea, come to a general consensus with the rest of the EB on the broad strokes, and then go off to make it happen with docs community members. After that, the EB member who owns the project could keep the rest of the EB in the loop or ask for input as issues arise.

jablonskidev · 2026-06-27T00:45:25Z

+
+## How this list works
+
+- **Every project has a committed lead.** This is not a wish list. A project is


When we say that all listed projects must have a committed lead, do we mean that we require all listed projects to have a project manager or just an EB board member associated with it? I like the idea of only requiring listed projects to have an EB member committed to it. That way, potential project leads have something concrete to say yes to.

jablonskidev · 2026-06-27T00:52:02Z

+
+- **Lead:** <name — required; no lead, no listing>
+- **Status:** Proposed | Active | Blocked | Done
+- **Summary:** One or two sentences on what this project delivers.


I like the idea of having both a short summary and a complete description. The short summary shows that there is a "there" there. The complete description lets contributors know what they're in for.

jablonskidev · 2026-06-27T00:59:51Z

+```markdown
+### <Project name>
+
+- **Lead:** <name — required; no lead, no listing>


We'll need to change this to "EB sponsor" if we decide that having an EB sponsor is enough to start a project.

We could follow this process:

EB member claims a project

EB member tries to find a project lead in the community:

EB member finds a project lead and supports them through the project

EB member does not find a project lead within a particular amount of time and then commits to being the project lead

That way, when an EB member commits to a project, they are committing to be a project lead if necessary but will first try to recruit a project lead from the community. We would need to set a time limit for recruiting a project lead from the community.

jablonskidev · 2026-06-27T01:01:37Z

+  unknowns, things that could derail it.
+- **How to help:** Concrete ways a contributor can get involved.
+- **Links:** Relevant issues, PRs, discussions, or docs.
+```


Do we want to add acceptance criteria to the project definition? It could make the project definition more concrete and helpful for people who haven't yet osmosed enough information about Python's docs to fill in the gaps themselves.

Mariatta requested a review from a team June 11, 2026 20:29

hugovk reviewed Jun 11, 2026

View reviewed changes

StanFromIreland reviewed Jun 11, 2026

View reviewed changes

nedbat reviewed Jun 11, 2026

View reviewed changes

Apply suggestions from code review

ad998cd

Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>

jablonskidev reviewed Jun 27, 2026

View reviewed changes


		## How this list works

		- Every project has a committed lead. This is not a wish list. A project is

Uh oh!

Conversation

Mariatta commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

New pages

Verification

Uh oh!

netlify Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for pythoneditorialboard ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Mariatta commented Jun 11, 2026 •

edited

Loading

netlify Bot commented Jun 11, 2026 •

edited

Loading