Here’s a new PEP that proposes how the Python Documentation Editorial Board will work:
Any feedback on this PEP would be appreciated.
Here’s a new PEP that proposes how the Python Documentation Editorial Board will work:
Any feedback on this PEP would be appreciated.
Is docs.python.org cpython documentation or python documentation? I’ve always thought of it as the latter, though cpython has pride of place as the reference implementation.
Is docs.python.org cpython documentation or python documentation?
This is a great question. In truth, it’s both. Implementation details (CPython-specific) are called out, but perhaps not as uniformly as they could be.
Are there particular issues you’re seeing with that tension?
The Python 3.x Reference is intended to define the Python 3.x language. Anything specific to CPython, such as ‘object ID = address’, should be noted as such. The PyPY implementation, in particular, forced some clarifications on what was ‘Python’ and what was specifically CPython. Any other implementation should describes its specializations and deviations. The Library Manual describes what come with CPython. Other implementations are at least encouraged to include everything not CPython specific. The C-API is obviously C specific.
Thank you for working on this! I’m +1 for both the PEP and the initial list of members.
The motivation section introduces the Working Group but not the Editorial Board. Could we have a single sentence explaining the relationship between the WG and the EB? For example, this is the EB of the WG.
This is partially explained by the diagram. For accessibility, it would help to add such a sentence in the body text, and/or something as alt text.
Great question @jacgoldsm. The Scope section of the PEP clarifies that docs.python.org is covered by this PEP.
@hugovk Thanks for highlighting that we have a terminology issue. It’s bound to happen since two distinct groups have had similar names.
When the Steering Council officially sanctioned a group to set direction for the docs, it used the term “working group.” Later, another documentation working group was set up, but it was focused on more tactical work. The original working group for documentation is now called the Editorial Board.
We now have two groups:
Does that clear it up?
Thank you! Yes, now I get it:
We had been calling group 1 the “Documentation Community Team” in our monthly meetings, for the community of volunteers:
And group 2 was called the “CPython Documentation Workgroup” for the initial formal group of decision makers:
I think two things might help:
For continuity, we keep the name of “Documentation Community Team” (or similar) for the community of volunteers contributing to the documentation (group 1). Avoiding “working group” for this looser group would avoid confusion with the original working group, which had a charter and membership votes and so on. Similarly with PSF Work Groups. Anyone can join in group 1: just turn up and get stuck in.
Update the info at CPython Documentation Workgroup - Documentation Community documentation to say the old WG is now the EB (could be mostly deleted and point to this PEP instead). Can of course wait until the PEP is accepted.
The SC has decided to accept PEP 732 (The Python Documentation Editorial Board). Our only comment is that while we don’t disagree with the scoping set out in the PEP, it would probably make sense for the EB 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. That can be discussed between the EB and SC when the time comes, however.