345 lines
19 KiB
HTML
345 lines
19 KiB
HTML
|
||
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="color-scheme" content="light dark">
|
||
<title>PEP 732 – The Python Documentation Editorial Board | peps.python.org</title>
|
||
<link rel="shortcut icon" href="../_static/py.png">
|
||
<link rel="canonical" href="https://peps.python.org/pep-0732/">
|
||
<link rel="stylesheet" href="../_static/style.css" type="text/css">
|
||
<link rel="stylesheet" href="../_static/mq.css" type="text/css">
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light">
|
||
<link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark">
|
||
<link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss">
|
||
<meta property="og:title" content='PEP 732 – The Python Documentation Editorial Board | peps.python.org'>
|
||
<meta property="og:description" content="This PEP:">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="https://peps.python.org/pep-0732/">
|
||
<meta property="og:site_name" content="Python Enhancement Proposals (PEPs)">
|
||
<meta property="og:image" content="https://peps.python.org/_static/og-image.png">
|
||
<meta property="og:image:alt" content="Python PEPs">
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="description" content="This PEP:">
|
||
<meta name="theme-color" content="#3776ab">
|
||
</head>
|
||
<body>
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
|
||
<symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Following system colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<circle cx="12" cy="12" r="9"></circle>
|
||
<path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Selected dark colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
|
||
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Selected light colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<circle cx="12" cy="12" r="5"></circle>
|
||
<line x1="12" y1="1" x2="12" y2="3"></line>
|
||
<line x1="12" y1="21" x2="12" y2="23"></line>
|
||
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
|
||
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
|
||
<line x1="1" y1="12" x2="3" y2="12"></line>
|
||
<line x1="21" y1="12" x2="23" y2="12"></line>
|
||
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
|
||
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
|
||
</svg>
|
||
</symbol>
|
||
</svg>
|
||
<script>
|
||
|
||
document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto"
|
||
</script>
|
||
<section id="pep-page-section">
|
||
<header>
|
||
<h1>Python Enhancement Proposals</h1>
|
||
<ul class="breadcrumbs">
|
||
<li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li>
|
||
<li><a href="../pep-0000/">PEP Index</a> » </li>
|
||
<li>PEP 732</li>
|
||
</ul>
|
||
<button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())">
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg>
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg>
|
||
<span class="visually-hidden">Toggle light / dark / auto colour theme</span>
|
||
</button>
|
||
</header>
|
||
<article>
|
||
<section id="pep-content">
|
||
<h1 class="page-title">PEP 732 – The Python Documentation Editorial Board</h1>
|
||
<dl class="rfc2822 field-list simple">
|
||
<dt class="field-odd">Author<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Joanna Jablonski</dd>
|
||
<dt class="field-even">Sponsor<span class="colon">:</span></dt>
|
||
<dd class="field-even">Mariatta Wijaya</dd>
|
||
<dt class="field-odd">Discussions-To<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710">Discourse thread</a></dd>
|
||
<dt class="field-even">Status<span class="colon">:</span></dt>
|
||
<dd class="field-even"><abbr title="Currently valid informational guidance, or an in-use process">Active</abbr></dd>
|
||
<dt class="field-odd">Type<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><abbr title="Normative PEP describing or proposing a change to a Python community process, workflow or governance">Process</abbr></dd>
|
||
<dt class="field-even">Topic<span class="colon">:</span></dt>
|
||
<dd class="field-even"><a class="reference external" href="../topic/governance/">Governance</a></dd>
|
||
<dt class="field-odd">Created<span class="colon">:</span></dt>
|
||
<dd class="field-odd">14-Oct-2023</dd>
|
||
<dt class="field-even">Post-History<span class="colon">:</span></dt>
|
||
<dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710" title="Discourse thread">20-Oct-2023</a></dd>
|
||
<dt class="field-odd">Resolution<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710/9">Discourse message</a></dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<section id="contents">
|
||
<details><summary>Table of Contents</summary><ul class="simple">
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#motivation">Motivation</a></li>
|
||
<li><a class="reference internal" href="#specification">Specification</a><ul>
|
||
<li><a class="reference internal" href="#mandate">Mandate</a></li>
|
||
<li><a class="reference internal" href="#responsibilities">Responsibilities</a></li>
|
||
<li><a class="reference internal" href="#scope">Scope</a><ul>
|
||
<li><a class="reference internal" href="#composition">Composition</a></li>
|
||
<li><a class="reference internal" href="#editorial-board-members">Editorial Board Members</a></li>
|
||
<li><a class="reference internal" href="#editorial-board-member-qualifications">Editorial Board Member Qualifications</a></li>
|
||
<li><a class="reference internal" href="#term">Term</a></li>
|
||
<li><a class="reference internal" href="#changes-to-the-editorial-board-s-size">Changes to the Editorial Board’s Size</a></li>
|
||
<li><a class="reference internal" href="#vacancies">Vacancies</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#amendments">Amendments</a></li>
|
||
<li><a class="reference internal" href="#pep-acceptance">PEP Acceptance</a></li>
|
||
<li><a class="reference internal" href="#contact">Contact</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
</details></section>
|
||
<section id="abstract">
|
||
<h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2>
|
||
<p>This PEP:</p>
|
||
<ul class="simple">
|
||
<li>Establishes the Python Documentation Editorial Board</li>
|
||
<li>Proposes how the editorial board will work</li>
|
||
</ul>
|
||
</section>
|
||
<section id="motivation">
|
||
<h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2>
|
||
<p>The Steering Council approved the creation of a
|
||
<a class="reference external" href="https://github.com/python/docs-community/blame/main/docs/workgroup/workgroup_charter.rst">Documentation Working Group</a>
|
||
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.</p>
|
||
<p>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:</p>
|
||
<a class="invert-in-dark-mode reference internal image-reference" href="../_images/pep-0732-concentric.drawio.svg"><img 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 align-center" src="../_images/pep-0732-concentric.drawio.svg" style="width: 75%;" />
|
||
</a>
|
||
</section>
|
||
<section id="specification">
|
||
<h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2>
|
||
<section id="mandate">
|
||
<h3><a class="toc-backref" href="#mandate" role="doc-backlink">Mandate</a></h3>
|
||
<p>The editorial board will:</p>
|
||
<ul class="simple">
|
||
<li>Ensure processes are in place to maintain and improve the quality of Python’s documentation</li>
|
||
<li>Foster Python documentation as a community resource to serve the current and future users</li>
|
||
<li>Act in alignment with the <a class="reference external" href="https://www.python.org/psf/mission/">Python Software Foundation mission</a>, which is to advance the Python
|
||
programming language, and to support and facilitate the growth of a diverse
|
||
and international community of Python programmers</li>
|
||
<li>Ensure that contributing to documentation is accessible, inclusive, and sustainable</li>
|
||
<li>Establish appropriate decision-making processes for documentation content</li>
|
||
<li>Seek to achieve consensus among contributors prior to making decisions</li>
|
||
<li>Be the final arbiter for documentation content decisions</li>
|
||
</ul>
|
||
</section>
|
||
<section id="responsibilities">
|
||
<h3><a class="toc-backref" href="#responsibilities" role="doc-backlink">Responsibilities</a></h3>
|
||
<p>The board has authority to make decisions about Python’s
|
||
documentation, as scoped below. For example, it can:</p>
|
||
<ul class="simple">
|
||
<li>Set big-picture strategy for Python’s documentation</li>
|
||
<li>Set the intended structure for documentation</li>
|
||
<li>Make style and editorial decisions for both writing and design</li>
|
||
<li>Handle documentation governance (for example, delegation of decision-making
|
||
to subject-matter experts, resolution of disagreements, decisions.)</li>
|
||
</ul>
|
||
</section>
|
||
<section id="scope">
|
||
<h3><a class="toc-backref" href="#scope" role="doc-backlink">Scope</a></h3>
|
||
<p>The Editorial board oversees the content and strategy for the following:</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 50.0%" />
|
||
<col style="width: 50.0%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head">In scope</th>
|
||
<th class="head">Not in scope</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td>CPython documentation (docs.python.org)</td>
|
||
<td>Code comments in CPython codebase</td>
|
||
</tr>
|
||
<tr class="row-odd"><td>CPython devguide (devguide.python.org)</td>
|
||
<td>CPython docstrings</td>
|
||
</tr>
|
||
<tr class="row-even"><td>Translations of CPython docs</td>
|
||
<td>PEPs (peps.python.org)</td>
|
||
</tr>
|
||
<tr class="row-odd"><td></td>
|
||
<td>PyPA documentation</td>
|
||
</tr>
|
||
<tr class="row-even"><td></td>
|
||
<td>www.python.org</td>
|
||
</tr>
|
||
<tr class="row-odd"><td></td>
|
||
<td>The Python Wiki (wiki.python.org)</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<section id="composition">
|
||
<h4><a class="toc-backref" href="#composition" role="doc-backlink">Composition</a></h4>
|
||
<p>The Python Documentation Editorial Board is composed of five members.</p>
|
||
</section>
|
||
<section id="editorial-board-members">
|
||
<h4><a class="toc-backref" href="#editorial-board-members" role="doc-backlink">Editorial Board Members</a></h4>
|
||
<p>The initial Editorial Board members are:</p>
|
||
<ul class="simple">
|
||
<li>Mariatta Wijaya</li>
|
||
<li>Ned Batchelder</li>
|
||
<li>Joanna Jablonski</li>
|
||
<li>Guido van Rossum</li>
|
||
<li>Carol Willing</li>
|
||
</ul>
|
||
</section>
|
||
<section id="editorial-board-member-qualifications">
|
||
<h4><a class="toc-backref" href="#editorial-board-member-qualifications" role="doc-backlink">Editorial Board Member Qualifications</a></h4>
|
||
<p>Editorial board members should have:</p>
|
||
<ul class="simple">
|
||
<li>A good grasp of the philosophy of the Python project</li>
|
||
<li>A background in Python education and developer-facing documentation</li>
|
||
<li>A solid track record of being constructive and helpful</li>
|
||
<li>A history of making significant contributions to Python</li>
|
||
<li>A willingness to dedicate time to improving Python’s docs</li>
|
||
</ul>
|
||
<p>Members of the Editorial Board should have experience in education,
|
||
communication, technical writing, Python’s documentation, accessibility,
|
||
translation, or community management.</p>
|
||
</section>
|
||
<section id="term">
|
||
<h4><a class="toc-backref" href="#term" role="doc-backlink">Term</a></h4>
|
||
<p>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.</p>
|
||
<p>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.</p>
|
||
</section>
|
||
<section id="changes-to-the-editorial-board-s-size">
|
||
<h4><a class="toc-backref" href="#changes-to-the-editorial-board-s-size" role="doc-backlink">Changes to the Editorial Board’s Size</a></h4>
|
||
<p>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.</p>
|
||
<p>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.</p>
|
||
</section>
|
||
<section id="vacancies">
|
||
<h4><a class="toc-backref" href="#vacancies" role="doc-backlink">Vacancies</a></h4>
|
||
<p>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.</p>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
<section id="amendments">
|
||
<h2><a class="toc-backref" href="#amendments" role="doc-backlink">Amendments</a></h2>
|
||
<p>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.</p>
|
||
</section>
|
||
<section id="pep-acceptance">
|
||
<h2><a class="toc-backref" href="#pep-acceptance" role="doc-backlink">PEP Acceptance</a></h2>
|
||
<p><a class="pep reference internal" href="../pep-0732/" title="PEP 732 – The Python Documentation Editorial Board">PEP 732</a> was <a class="reference external" href="https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710/8">accepted by the Python Steering Council on December 11, 2023</a>.</p>
|
||
<p>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.</p>
|
||
</section>
|
||
<section id="contact">
|
||
<h2><a class="toc-backref" href="#contact" role="doc-backlink">Contact</a></h2>
|
||
<p>To ask the Editorial Board for a decision,
|
||
community members may open an issue in the
|
||
<a class="reference external" href="https://github.com/python/editorial-board/">python/editorial-board</a>
|
||
repository.</p>
|
||
</section>
|
||
<section id="copyright">
|
||
<h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2>
|
||
<p>This document is placed in the public domain or under the
|
||
CC0-1.0-Universal license, whichever is more permissive.</p>
|
||
</section>
|
||
</section>
|
||
<hr class="docutils" />
|
||
<p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0732.rst">https://github.com/python/peps/blob/main/peps/pep-0732.rst</a></p>
|
||
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0732.rst">2024-02-28 06:14:55 GMT</a></p>
|
||
|
||
</article>
|
||
<nav id="pep-sidebar">
|
||
<h2>Contents</h2>
|
||
<ul>
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#motivation">Motivation</a></li>
|
||
<li><a class="reference internal" href="#specification">Specification</a><ul>
|
||
<li><a class="reference internal" href="#mandate">Mandate</a></li>
|
||
<li><a class="reference internal" href="#responsibilities">Responsibilities</a></li>
|
||
<li><a class="reference internal" href="#scope">Scope</a><ul>
|
||
<li><a class="reference internal" href="#composition">Composition</a></li>
|
||
<li><a class="reference internal" href="#editorial-board-members">Editorial Board Members</a></li>
|
||
<li><a class="reference internal" href="#editorial-board-member-qualifications">Editorial Board Member Qualifications</a></li>
|
||
<li><a class="reference internal" href="#term">Term</a></li>
|
||
<li><a class="reference internal" href="#changes-to-the-editorial-board-s-size">Changes to the Editorial Board’s Size</a></li>
|
||
<li><a class="reference internal" href="#vacancies">Vacancies</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#amendments">Amendments</a></li>
|
||
<li><a class="reference internal" href="#pep-acceptance">PEP Acceptance</a></li>
|
||
<li><a class="reference internal" href="#contact">Contact</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
|
||
<br>
|
||
<a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0732.rst">Page Source (GitHub)</a>
|
||
</nav>
|
||
</section>
|
||
<script src="../_static/colour_scheme.js"></script>
|
||
<script src="../_static/wrap_tables.js"></script>
|
||
<script src="../_static/sticky_banner.js"></script>
|
||
</body>
|
||
</html> |