Clean up, fix and improve grammar, phrasing, syntax/links and overall prose quality in charter #29
Conversation
|
@willingc It looks like you committed the original (I don't even have triage rights on this repo, so I can't tag you for review) |
Maybe a third of this is a review of the changes proposed by Cam, and the rest is things I noticed with my reviewing terms of reference hat on.
I support most of Cam's changes, although it is slightly hard to tell what he changed in the interface given the file rename, so I treated the proposed text as the actual text and reviewed everything.
A
docs/workgroup/charter.rst
Outdated
| Purpose & Common Goals | ||
| ---------------------- | ||
|
|
||
| This workgroup will support efforts to improve |
There was a problem hiding this comment.
The title says "working group" but this says "workgroup" -- appreciate your (@CAM-Gerlach's) point on consistency in the PR body, but it feels odd to leave it unadressed in a copyediting pass such as this.
There was a problem hiding this comment.
I do hope to address this here; per our discussion on Discord as well as mentioned here, I'm just hoping to get some clarity on nomenclature first before going through and changing it everywhere.
The problem is the PSF itself is not at all consistent on this. Just on their main workgroup page alone, they use "workgroups" in the title, "work group" in the top level headings and "working group" in many of the resolutions and descriptions (and both workgroup and work group in others). In total, "work group" is used 40 times (mostly in the headings), "workgroup" 15 times and "working group" 12 times. Plus "committee" is used 46 times, aside from in the URL itself, mostly interchangeably with the previous three.
"Workgroup" (and WG) is used on the example workgroup page and the example charter, but the title of every "workgroup" page uses "Working Group". and the charters and info pages use a mix of all three. Ughhhhhh...
| Things the workgroup could do: | ||
|
|
||
| - Develop the governance model for docs | ||
| - Be the steering council for docs | ||
| - Be the authors of doc guidelines | ||
| - Be the authors/editors of docs | ||
| - Request grant funding from PSF, if needed | ||
| - Form an editorial board for docs including core devs, educators, and | ||
| documentarians in the Python community |
There was a problem hiding this comment.
Given that the group has started, this list feels out of place -- perhaps it should move to a TODO document? A speculative list seems off for a terms of reference.
There was a problem hiding this comment.
I agree with that logic, but that would be a pretty significant content-relevant change in what I scoped to be a copyediting-focused PR with minimal substantive changes to the actual content/meaning. If others agree, I can make it here, otherwise we can do so in a separate PR.
There was a problem hiding this comment.
I think it's fine for a charter to include a list of possible work. It helps makes the details more concrete.
| The workgroup adopts the `PSF Code of Conduct <https://www.python.org/psf/codeofconduct/>`_. | ||
| Any action by a workgroup member, as decided by a majority of the group, | ||
| that violates the principles in the Code of Conduct will result in that member | ||
| being removed from the workgroup. |
There was a problem hiding this comment.
Pedantic governance point -- how does this fit with "The Python Steering Council are permanent members of this working group"? Are such ex-officio members included in this section?
There was a problem hiding this comment.
The CoC governs SC members just like any other member of the PSF/Python project. If they committed a suitably serious CoC violation sufficient to merit removal, presumably that would be handled by the CoC committee rather than us, but they would be removed from the SC, and thus from the workgroup as well.
There was a problem hiding this comment.
I agree. That's not what this text says though -- and whilst unlikely we should be accurate. I'm happy to suggest this one (and the TODO one above) in a follow-up PR if you don't want to include here.
A
There was a problem hiding this comment.
IMO, this seems a bit too pedantic to me to need to be explicitly denoted in the work(ing)? ?group's founding charter, but its ultimately up to the work(ing)? ?group' members, so I'll leave it to their decision.
@willingc , thoughts?
| as the developer guide. Translations and infrastructure will be managed by | ||
| Julien Palard or a Steering Council appointed member. | ||
| - The group will also maintain documentation of meetings and best practices. | ||
| - The editorial board will include people outside of the core developers who are |
There was a problem hiding this comment.
The document switches between working group and editorial board -- I think the two are the same, but we should use one term for consistency
There was a problem hiding this comment.
At least based on my reading of the Charter, the editorial board is nominally a related but distinct function that the WG members currently serve as.
| Julien Palard or a Steering Council appointed member. | ||
| - The group will also maintain documentation of meetings and best practices. | ||
| - The editorial board will include people outside of the core developers who are | ||
| tech writers or educators. |
There was a problem hiding this comment.
Do we want to restrict to just these categories?
There was a problem hiding this comment.
Those seem the most reasonable, but we could hedge here—that would be a content-relevant change, though, and one I would defer to the work group members on.
| - Increase the participation of contributors to documentation. | ||
|
|
||
| To be considered for membership, prospective members must send an | ||
| email introducing themselves, along with a description of why they want to be |
There was a problem hiding this comment.
No idea. This needs to be updated, but not within my purview as a copyeditor.
There was a problem hiding this comment.
After this gets merged I'll capture all of the problems I found that are broader than strict copy-editing so that they dion't get lost.
A
There was a problem hiding this comment.
Good point, though this actually is mostly captured by #3
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
|
Sidenote, but sorry I was a bit grumpy late last night with a few of my review replies, @AA-Turner . Thanks as always for your detailed feedback. |
|
@willingc or others—any chance of a review on this (realized I didn't actually tag you)? |
My review was re-requested -- I'm not a member of the formal group and as such don't have a vote about adopting this wording, but it looks fine from a pure technical editing perspective.
If I were going through the bother of a formal vote though, I'd also want to address some of the other points raised here.
Regardless, I wonder to what extent this terms of reference actually matter, as the intent seems to be for the "community" body to do most things, so perhaps almost no-one should need to care about this.
A
Fair point; assuming that there is considerable overhead to changing it, while this document is still (AFAIK) a draft, I'm happy to make such changes here if the WG members prefer it.
Yeah, though it is required by the PSF and should at least be accurate, accessible and not confusion or misleading for those who do come across it. My hope was that this would be a "one and done" fix rather than requiring continuing updates, which some of your suggestions (particularly the outstanding one about removing the "some of the things the workgroup could do" section) help further. |
|
A meta point for everyone re: PSF and Python Steering Council. The Python Docs Workgroup was never intended to be a PSF chartered workgroup. Instead, this is a workgroup of the Python Steering Council. See https://discuss.python.org/t/documentation-community-meeting-april-4th/14775/23?u=willingc |
We also should be consistent about the full and short name of the group, and what it is referred to as ("workgroup"? "work group"? "working group"? or something else more appropriate?), and more importantly clarify how it relates to the docs team, docs community and what those really are, but I've deferred that to a separate issue for now.