Add Board Roles and Projects pages#41
Conversation
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>
✅ Deploy Preview for pythoneditorialboard ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
| - 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. |
There was a problem hiding this comment.
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?
|
|
||
| - 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. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
| - **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. |
There was a problem hiding this comment.
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.
|
|
||
| - 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. |
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
Here is where the EB member is described as the project lead. Whatever we decide above, this sentence needs to match.
|
|
||
| _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._ |
There was a problem hiding this comment.
Also: recognizing when a project isn't working out, and wrapping it up even though it wasn't done.
|
|
||
| - **Lead:** <name — required; no lead, no listing> | ||
| - **Status:** Proposed | Active | Blocked | Done | ||
| - **Summary:** One or two sentences on what this project delivers. |
There was a problem hiding this comment.
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.
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
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. IncludesTODOs 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 --minifybuilds clean (71 pages, no errors); both pages render and appear in the nav.