206 lines
6.8 KiB
ReStructuredText
206 lines
6.8 KiB
ReStructuredText
PEP: 732
|
||
Title: The Python Documentation Editorial Board
|
||
Author: Joanna Jablonski
|
||
Sponsor: Mariatta Wijaya
|
||
Discussions-To: https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710
|
||
Status: Active
|
||
Type: Process
|
||
Topic: Governance
|
||
Created: 14-Oct-2023
|
||
Post-History: `20-Oct-2023 <https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710>`__
|
||
Resolution: https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710/9
|
||
|
||
|
||
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 <https://github.com/python/docs-community/blame/main/docs/workgroup/workgroup_charter.rst>`_
|
||
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:
|
||
|
||
.. image:: pep-0732-concentric.drawio.svg
|
||
:align: center
|
||
:alt: Three concentric circles. At the centre: Documentation Editorial
|
||
Board, trusted group. Around this: Documentation Working Group,
|
||
volunteers who contribute to the docs. Finally, the outer circle
|
||
is the world, includes readers of the documentation.
|
||
:class: invert-in-dark-mode
|
||
:width: 75%
|
||
|
||
|
||
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
|
||
<https://www.python.org/psf/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:
|
||
|
||
.. list-table::
|
||
:widths: 50 50
|
||
:header-rows: 1
|
||
|
||
* - 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
|
||
<https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710/8>`_.
|
||
|
||
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 <https://github.com/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.
|