diff --git a/content/expectations.md b/content/expectations.md new file mode 100644 index 0000000..4453ff1 --- /dev/null +++ b/content/expectations.md @@ -0,0 +1,90 @@ +--- +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 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 either sponsor or 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 it is desirable, has been realistically scoped, and major decisions have been made. There may not yet be an EB sponsor, but one will be identified before the project is started. The projects are ready for someone to start working on them; they have been concretely scoped out. +- 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 overseeing these efforts, not merely naming them. We are committed to supporting the docs community in finishing 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). + +### What it means to sponsor 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 +- Sponsor the project, support the work in the docs community +- See the project through to completion, or shut it down if it won't be completed + +## 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..8f8ece5 --- /dev/null +++ b/content/projects.md @@ -0,0 +1,75 @@ +--- +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 have identified as valuable and actionable. 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 active project has a committed lead.** If a project loses its lead, it + becomes Blocked 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 in the [Python Docs Discord](https://discord.gg/nXkJ2JYvCu). + +## Project template + +Once a project is approved by the Editorial Board, copy this block to add a new project. + +```markdown +### + +- **Sponsor:** +- **Lead:** +- **Status:** Proposed | Active | Blocked | Done +- **Summary:** One or two sentences on what this project delivers. +- **Full issue:** A link to the issue (in this repo or elsewhere) that fully describes the project. Include complete description, decisions made, challenges/risks, acceptance criteria, etc. +- **Why it matters:** Who benefits and why this is worth doing now. +- **How to help:** Concrete ways a contributor can get involved. +- **Links:** Other relevant issues, PRs, discussions, or docs, if any. +``` + +## Projects + +_None listed yet. Add projects here using the template above._ Order them by rough priority with active projects first. + + 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