python-peps/peps/pep-0732.rst

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.