From 862ea5914f9cec8ca4aa2910fa66447a2b632543 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Sat, 14 Oct 2023 06:42:01 -0700 Subject: [PATCH 01/14] Create pep-NNNN.rst --- peps/pep-NNNN/pep-NNNN.rst | 163 +++++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 peps/pep-NNNN/pep-NNNN.rst diff --git a/peps/pep-NNNN/pep-NNNN.rst b/peps/pep-NNNN/pep-NNNN.rst new file mode 100644 index 00000000000..0334135a74a --- /dev/null +++ b/peps/pep-NNNN/pep-NNNN.rst @@ -0,0 +1,163 @@ +PEP: NNNN +Title: The Python Documentation Editorial Board +Author: Joanna Jablonski +Sponsor: Mariatta Wijaya +Status: Draft +Type: Process +Topic: Governance +Content-Type: text/x-rst +Created: 30-May-2323 + + +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. + +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:: docs-pep-concentric.drawio.svg + + +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 + +Responsiblities +--------------- + +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 + +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. + +Copyright +========= + +This document has been placed in the public domain or under the +CC0-1.0-Universal license, whichever is more permissive. From 25f36b689dacc3357acbfdd60ad552fc3d2aa89f Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Sat, 14 Oct 2023 06:44:24 -0700 Subject: [PATCH 02/14] Add venn diagram --- peps/pep-NNNN/docs-pep-concentric.drawio.svg | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 peps/pep-NNNN/docs-pep-concentric.drawio.svg diff --git a/peps/pep-NNNN/docs-pep-concentric.drawio.svg b/peps/pep-NNNN/docs-pep-concentric.drawio.svg new file mode 100644 index 00000000000..02677c5ee5c --- /dev/null +++ b/peps/pep-NNNN/docs-pep-concentric.drawio.svg @@ -0,0 +1,4 @@ + + + +
3   
3   
2   
2   
1
1
1
1
2
2
3
3
World
includes readers of the documentation
World...
Documentation Working Group
volunteers who contribute to the docs
Documentation Working Group...
Documentation Editoral Board
trusted group
Documentation Editoral Board...Text is not SVG - cannot display \ No newline at end of file From c7e22b81e5ad75bf9a284f7f9f5dd3b5ad284e2e Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Tue, 17 Oct 2023 18:47:33 -0700 Subject: [PATCH 03/14] Move to pep-0732 and fix creation date in the future --- peps/{pep-NNNN/pep-NNNN.rst => pep-0732.rst} | 4 ++-- peps/{pep-NNNN => pep-0732}/docs-pep-concentric.drawio.svg | 0 2 files changed, 2 insertions(+), 2 deletions(-) rename peps/{pep-NNNN/pep-NNNN.rst => pep-0732.rst} (99%) rename peps/{pep-NNNN => pep-0732}/docs-pep-concentric.drawio.svg (100%) diff --git a/peps/pep-NNNN/pep-NNNN.rst b/peps/pep-0732.rst similarity index 99% rename from peps/pep-NNNN/pep-NNNN.rst rename to peps/pep-0732.rst index 0334135a74a..314f4a1fd8a 100644 --- a/peps/pep-NNNN/pep-NNNN.rst +++ b/peps/pep-0732.rst @@ -1,4 +1,4 @@ -PEP: NNNN +PEP: 732 Title: The Python Documentation Editorial Board Author: Joanna Jablonski Sponsor: Mariatta Wijaya @@ -6,7 +6,7 @@ Status: Draft Type: Process Topic: Governance Content-Type: text/x-rst -Created: 30-May-2323 +Created: 30-May-2023 Abstract diff --git a/peps/pep-NNNN/docs-pep-concentric.drawio.svg b/peps/pep-0732/docs-pep-concentric.drawio.svg similarity index 100% rename from peps/pep-NNNN/docs-pep-concentric.drawio.svg rename to peps/pep-0732/docs-pep-concentric.drawio.svg From 71f09de3ebc59558d01315140f3b5725e0e86461 Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Tue, 17 Oct 2023 18:59:22 -0700 Subject: [PATCH 04/14] Fix image reference --- peps/pep-0732.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0732.rst b/peps/pep-0732.rst index 314f4a1fd8a..d0bafebeb0d 100644 --- a/peps/pep-0732.rst +++ b/peps/pep-0732.rst @@ -29,7 +29,7 @@ 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:: docs-pep-concentric.drawio.svg +.. image:: pep-0732/docs-pep-concentric.drawio.svg Specification From ce307c1763af54ef1b39b8e392857136052646aa Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Wed, 18 Oct 2023 06:05:30 -0700 Subject: [PATCH 05/14] Changed date and spelling --- peps/pep-0732.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/peps/pep-0732.rst b/peps/pep-0732.rst index d0bafebeb0d..da222aaaf22 100644 --- a/peps/pep-0732.rst +++ b/peps/pep-0732.rst @@ -6,7 +6,7 @@ Status: Draft Type: Process Topic: Governance Content-Type: text/x-rst -Created: 30-May-2023 +Created: 14-Oct-2023 Abstract @@ -72,7 +72,7 @@ The Editorial board oversees the content and strategy for the following: - Not in scope * - CPython documentation (docs.python.org) - Code comments in CPython codebase - * - CPython DevGuide (devguide.python.org) + * - CPython devguide (devguide.python.org) - CPython docstrings * - Translations of CPython docs - PEPs (peps.python.org) From 61fdba06225177b1aded7964931b006deb5d8776 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 19 Oct 2023 05:33:12 -0700 Subject: [PATCH 06/14] Update peps/pep-0732.rst Co-authored-by: Hugo van Kemenade --- peps/pep-0732.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/peps/pep-0732.rst b/peps/pep-0732.rst index da222aaaf22..4a787bab55a 100644 --- a/peps/pep-0732.rst +++ b/peps/pep-0732.rst @@ -30,6 +30,7 @@ development community and the greater Python documentation contributors work together to achieve this: .. image:: pep-0732/docs-pep-concentric.drawio.svg + :class: invert-in-dark-mode Specification From 5912723b61af21604f53c2e93a6e7a0a95210963 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 19 Oct 2023 05:33:27 -0700 Subject: [PATCH 07/14] Update peps/pep-0732.rst Co-authored-by: Hugo van Kemenade --- peps/pep-0732.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/peps/pep-0732.rst b/peps/pep-0732.rst index 4a787bab55a..a3cf34f9062 100644 --- a/peps/pep-0732.rst +++ b/peps/pep-0732.rst @@ -5,7 +5,6 @@ Sponsor: Mariatta Wijaya Status: Draft Type: Process Topic: Governance -Content-Type: text/x-rst Created: 14-Oct-2023 From d52c110c7ed0682622f860d76f04f74d55ff0d9a Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 19 Oct 2023 05:33:42 -0700 Subject: [PATCH 08/14] Update peps/pep-0732.rst Co-authored-by: Hugo van Kemenade --- peps/pep-0732.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0732.rst b/peps/pep-0732.rst index a3cf34f9062..5cb75ee9280 100644 --- a/peps/pep-0732.rst +++ b/peps/pep-0732.rst @@ -159,5 +159,5 @@ upon by the Steering Council after discussion in the community. Copyright ========= -This document has been placed in the public domain or under the +This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. From 9416ecfad535890a21ec8c0c74285190e53a8e58 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 19 Oct 2023 05:34:19 -0700 Subject: [PATCH 09/14] Update peps/pep-0732.rst Co-authored-by: Hugo van Kemenade --- peps/pep-0732.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0732.rst b/peps/pep-0732.rst index 5cb75ee9280..50c728c5bd6 100644 --- a/peps/pep-0732.rst +++ b/peps/pep-0732.rst @@ -42,7 +42,7 @@ 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 +* 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 From 2b771f120084080c2e0281e4342220a4914ff692 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 19 Oct 2023 05:34:39 -0700 Subject: [PATCH 10/14] Update peps/pep-0732.rst Co-authored-by: Hugo van Kemenade --- peps/pep-0732.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/peps/pep-0732.rst b/peps/pep-0732.rst index 50c728c5bd6..7259b45ed40 100644 --- a/peps/pep-0732.rst +++ b/peps/pep-0732.rst @@ -57,7 +57,8 @@ 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.) +* Handle documentation governance (for example, delegation of decision-making + to subject-matter experts, resolution of disagreements, decisions.) Scope ----- From dae73454c01621efcba53d18b7c5ffbabe728690 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 19 Oct 2023 05:40:35 -0700 Subject: [PATCH 11/14] Add Mariatta for PEP 732 --- .github/CODEOWNERS | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 25e077ef219..8d6ba17442f 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -609,6 +609,7 @@ peps/pep-0727.rst @JelleZijlstra peps/pep-0729.rst @JelleZijlstra @hauntsaninja peps/pep-0730.rst @ned-deily peps/pep-0731.rst @gvanrossum @encukou @vstinner @zooba @iritkatriel +peps/pep-0732.rst @Mariatta # ... # peps/pep-0754.rst # ... From 530e55d001c233d67b5a8280b138343cb5bbe2fe Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 19 Oct 2023 06:11:51 -0700 Subject: [PATCH 12/14] Move image file and update reference in rst --- peps/{pep-0732 => }/docs-pep-concentric.drawio.svg | 0 peps/pep-0732.rst | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename peps/{pep-0732 => }/docs-pep-concentric.drawio.svg (100%) diff --git a/peps/pep-0732/docs-pep-concentric.drawio.svg b/peps/docs-pep-concentric.drawio.svg similarity index 100% rename from peps/pep-0732/docs-pep-concentric.drawio.svg rename to peps/docs-pep-concentric.drawio.svg diff --git a/peps/pep-0732.rst b/peps/pep-0732.rst index 7259b45ed40..a298f37cfa8 100644 --- a/peps/pep-0732.rst +++ b/peps/pep-0732.rst @@ -28,7 +28,7 @@ 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/docs-pep-concentric.drawio.svg +.. image:: docs-pep-concentric.drawio.svg :class: invert-in-dark-mode From ddd3400f1e845576a42d4d94807adc9ca7a3bf7d Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 19 Oct 2023 07:24:05 -0700 Subject: [PATCH 13/14] Update peps/pep-0732.rst Co-authored-by: Hugo van Kemenade --- peps/pep-0732.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/peps/pep-0732.rst b/peps/pep-0732.rst index a298f37cfa8..c28d6590330 100644 --- a/peps/pep-0732.rst +++ b/peps/pep-0732.rst @@ -42,7 +42,10 @@ 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 +* 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 From aa02e3764e4d10fd8d88dec2b94ed74510cd7966 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 19 Oct 2023 07:27:12 -0700 Subject: [PATCH 14/14] Add prefix to filename and update rst --- ...pep-concentric.drawio.svg => pep-0732-concentric.drawio.svg} | 0 peps/pep-0732.rst | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename peps/{docs-pep-concentric.drawio.svg => pep-0732-concentric.drawio.svg} (100%) diff --git a/peps/docs-pep-concentric.drawio.svg b/peps/pep-0732-concentric.drawio.svg similarity index 100% rename from peps/docs-pep-concentric.drawio.svg rename to peps/pep-0732-concentric.drawio.svg diff --git a/peps/pep-0732.rst b/peps/pep-0732.rst index c28d6590330..0ab82d777a1 100644 --- a/peps/pep-0732.rst +++ b/peps/pep-0732.rst @@ -28,7 +28,7 @@ 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:: docs-pep-concentric.drawio.svg +.. image:: pep-0732-concentric.drawio.svg :class: invert-in-dark-mode