DOC: reasoning for communications guidelines #27249
Conversation
doc/devel/communication_guide.rst
Outdated
| the documentation and show recognition for work that may not be in the | ||
| “what’s new” section. |
There was a problem hiding this comment.
What kind of work is this? Can you write that positive, i.e. not as a negation?
There was a problem hiding this comment.
sure, but thinking stuff like running tutorials running the new contributor meetings, making third party libraries, we only just kinda started including docs in the whats new -> basically contributions that don't get merged into main
doc/devel/communication_guide.rst
Outdated
| Matplotlib. | ||
| * In prioritizing understandability and extensiblity, we empower people working | ||
| with Matplotlib to feel like they are a part of our community and that they are | ||
| doing valuable community building labor. |
There was a problem hiding this comment.
Is "working with Matplotlib" already valueable community building? Maybe "building on top of Matplotlib"? Also, you can leave out "labor", "doing valuable community building." is enough.
There was a problem hiding this comment.
It can be when they're making tutorials and giving talks - like I think we all agree that for example Nicholas Rougier has contributed immensely with his books and and cheatsheet
There was a problem hiding this comment.
And also the goal of this statement is to say that whatever the fluency of the person and stage they're at - new learner or seasoned dev, they participate in community building through engagement and sharing. I explicitly don't want to use "building on top of" b/c that's gonna sound like we only care about library builders and this is supposed to be far more general.
There was a problem hiding this comment.
basically in the yellow range here:
|
Semi-OT: When I saw this under "Contribute > Communication Guidelines" I got the impression that people wanting to contribute should read this and that it relates to how we communicate on github for issues and PRs. Should we rename the page to "Public communication guidelines" (or "Social media communication guidelines", which is maybe slightly too narrow but even more clear that not every contributor does not have to care about it. |
|
I wrote the communications guide years back 'cause I was trying to get folks to help w/ social media and discourse and the like, so it was always intended as "comms guide when acting as a representative of the project" - i.e. any kinda community facing/community building role. The stock github responses PR is #23109, which should be a lot easier to get in now that we've rewritten workflows again. But also frankly, the way I see it is that one of the responsibilities of being a maintainer is being a public facing representative of the project. I can tell a contributor "no no, I'm speaking for me, not Matplotlib" but like if I'm being a jerk that's what the culture of the project is gonna read as. Which is also why I put this in the maintainers section rather then one of the other bins. We can definitely have a discussion on if this is the direction folks want to aim for w/ our communications <- the contents of this PR were intended to seed a discussion around our communication strategy/goals/objectives". Though to be clear, I'm not trying to police how maintainers communicate , even if I had the authority to. This PR is mostly aimed at adding the context around why the guidelines are what they are. For example, that our topics list is viz and other libraries 'cause our mission is viz+extensibility, our social media is chill b/c our mission is empowering folks to build things, etc.-> which found name: community engagement guidelines |
58c64b9 to
0925a35
Compare
|
The comm guide state the scope at the top
I'd like to capture this in the title, in particular with the intent to make it obvious for a first-time contributor that they do not need to worry about this when posting an issue or PR. |
dcd96a5 to
82efb86
Compare
|
So I think community engagement should work then b/c most folks don't think of issues/PRs as community engagement, but also
What in the guide do you think would make a new contributor think that they DO have to worry about this? I pulled the sentence you're highlighting up to the top so that if they do land here they can bounce out, but I'm also a little confused where your concern is coming from given that the only explicit "how to communicate" guidelines are in the social media subsection. |
5e590a0 to
c79d053
Compare
Nothing in there, it's the title that is too generic. When you go to contribution entry page https://matplotlib.org/devdocs/devel/index.html, you get a side bar with lots of entries:
which is quite overwhelming, For some, like Release guide, it's clear that I as a first-time contributor does not have to care about. It would be helpful if that would come across also in the communication heading (and/or possibly better separation between topics relevant to the majority of contributors, and topics only relevant to special people). |
|
Yeah I think the problem is more that the card headers don't show up as page headers and therefore that organization isn't in the sidebar but maybe this is clearer?
ETA: at the least, that sidebar should maybe follow the page ordering in the same way as the page/listed in the page ? |
|
Borrowing from cscce, maybe call this the "community management guide"? It's a bit broader than the specifics but also if you're looking for a "no not doing that" title it'll work? & matches a dpl title like release guide manages release manager? |
|
The organization of the index is ideally the organization of the cards. |
working towards that? if #27213 goes in, as a follow up in that PR I have proposals to clean up the rest of the policy and guidelines so at least each card is just a toc |
c79d053 to
4266576
Compare
+ update to changing guidelines section to be name of doc agnostic Co-authored-by: Melissa Weber Mendonça <melissawm@gmail.com> Co-authored-by: noatamir <6564007+noatamir@users.noreply.github.com>
4266576 to
f213801
Compare
…249-on-v3.8.1-doc Backport PR #27249 on branch v3.8.1-doc (DOC: reasoning for communications guidelines)
…249-on-v3.8.x Backport PR #27249 on branch v3.8.x (DOC: reasoning for communications guidelines)
PR summary
Follow up to #26703, last winter(ish) @melissawm, @noatamir, and me worked on writing up the reasoning for the communications guidelines and objectives for the strategy. I figure especially w/ the move to the main repo, it's worth having it in the doc as grounding for the guidelines.
PR checklist