PEP 732 – The Python Documentation Editorial Board
- Author:
- Joanna Jablonski
- Sponsor:
- Mariatta Wijaya
- Discussions-To:
- Discourse thread
- Status:
- Active
- Type:
- Process
- Topic:
- Governance
- Created:
- 14-Oct-2023
- Post-History:
- 20-Oct-2023
- Resolution:
- Discourse message
Abstract
This PEP:
- Establishes the Python Documentation Editorial Board
- Proposes how the editorial board will work
Motivation
The Steering Council approved the creation of a Documentation Working Group in March 2021 to set direction for the docs. This group is now called the Editorial Board to differentiate it from the Documentation Working Group that was created since then to focus on more tactical work.
The purpose of the Python documentation is to serve the present and future end users of Python. As such, the core development community and the greater Python documentation contributors work together to achieve this:
Specification
Mandate
The editorial board will:
- Ensure processes are in place to maintain and improve the quality of Python’s documentation
- Foster Python documentation as a community resource to serve the current and future users
- Act in alignment with the Python Software Foundation mission, which is to advance the Python programming language, and to support and facilitate the growth of a diverse and international community of Python programmers
- Ensure that contributing to documentation is accessible, inclusive, and sustainable
- Establish appropriate decision-making processes for documentation content
- Seek to achieve consensus among contributors prior to making decisions
- Be the final arbiter for documentation content decisions
Responsibilities
The board has authority to make decisions about Python’s documentation, as scoped below. For example, it can:
- Set big-picture strategy for Python’s documentation
- Set the intended structure for documentation
- Make style and editorial decisions for both writing and design
- Handle documentation governance (for example, delegation of decision-making to subject-matter experts, resolution of disagreements, decisions.)
Scope
The Editorial board oversees the content and strategy for the following:
| In scope | Not in scope |
|---|---|
| CPython documentation (docs.python.org) | Code comments in CPython codebase |
| CPython devguide (devguide.python.org) | CPython docstrings |
| Translations of CPython docs | PEPs (peps.python.org) |
| PyPA documentation | |
| www.python.org | |
| The Python Wiki (wiki.python.org) |
Composition
The Python Documentation Editorial Board is composed of five members.
Editorial Board Members
The initial Editorial Board members are:
- Mariatta Wijaya
- Ned Batchelder
- Joanna Jablonski
- Guido van Rossum
- Carol Willing
Editorial Board Member Qualifications
Editorial board members should have:
- A good grasp of the philosophy of the Python project
- A background in Python education and developer-facing documentation
- A solid track record of being constructive and helpful
- A history of making significant contributions to Python
- A willingness to dedicate time to improving Python’s docs
Members of the Editorial Board should have experience in education, communication, technical writing, Python’s documentation, accessibility, translation, or community management.
Term
Editorial Board members serve for an indefinite term, though it is generally expected that there will be changes in Editorial Board composition each year. Editorial Board members will confirm annually whether they wish to continue as a board member. Members may resign at any time.
If a board member drops out of touch and cannot be contacted for a month or longer, then the rest of the board may vote to replace them.
Changes to the Editorial Board’s Size
Annually after each major Python release, the Editorial Board will review whether the board’s size should change. This provides flexibility if the needs of the documentation community change over time. A simple majority is needed to make a decision to increase the board’s size where quorum is 80% of the current board.
As the sponsoring organization of the Documentation Editorial Board, the Steering Council may change the number of members of the Board at any time, including appointing new members or dismissing existing members.
Vacancies
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.
Amendments
This PEP serves as a charter for the Docs Editorial Board. Changes to its operation can be made either through a new PEP or through a change to this PEP. In either case, the change would be decided upon by the Steering Council after discussion in the community.
PEP Acceptance
PEP 732 was accepted by the Python Steering Council on December 11, 2023.
The Steering Council commented that, while they don’t disagree with the scoping set out in the PEP, it would probably make sense for the Editorial Board to consider expanding the scope to include docstrings in the standard library, once the Board is sufficiently established and the higher priorities have been taken care of.
Contact
To ask the Editorial Board for a decision, community members may open an issue in the python/editorial-board repository.
Copyright
This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.
Source: https://github.com/python/peps/blob/main/peps/pep-0732.rst
Last modified: 2024-02-28 06:14:55 GMT