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 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 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:

[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, 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               Code comments in CPython codebase
  (docs.python.org)                   

  CPython devguide                    CPython docstrings
  (devguide.python.org)               

  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.