Hey all - at the team meeting we had a lot of useful discussion about communications channels in the JupyterHub project. I don’t believe that we had any specific outcome from this, so I wanted to take a stab at a proposal for our communications strategy on the hub side of things to hear what the community thinks.
tl;dr
Use GitHub repositories for repository-specific questions related to the codebase. Things that should ultimately result in a change to that repository.
Use Gitter for live conversation that don’t need to be archived/read by anyone not present in the moment
Use Discourse for general “how do I?” questions, generic suggestions, ideas, etc. If in doubt post here.
Use Twitter/Blog/Discourse to highlight new activity and updates in the community
What’s the goal
The goal for this proposal is to make it easier to know what kind of information goes in which channel, to help improve the signal to noise of our repository issues, and to use the “right tool for the job” when it comes to communication. It is also a way to signal to the community how they can best-engage with the project.
What process exists around these channels?
GitHub is a platform designed around making changes to code repositories. Issues have a very “ask the core dev team” feel about them, and the notion of “closing” issues suggests that in general they should be actionable (or at least of finite time). This makes GitHub awkward if you want more general conversations and sharing about the use of technology, or if you want to encourage more user-to-user interactions. As such, I propose that we focus GitHub issue conversations around questions/conversations that will lead to changes in the code repository. If people ask other kinds of questions there (“e.g., I’m trying to deploy XXX, can somebody help me?”) then we post a friendly suggestion that they open a thread on the discourse page and close the issue. The goal is that GitHub issues are focused on actionable and specific items for a repository.
Gitter is a great medium for fluid conversation, though it isn’t easily searchable/archivable/discoverable and so we’d like to keep content-full discussion in either GitHub or Discourse. Once conversations on Gitter start to become non-trivial (e.g. will take some thinking to resolve), we recommend that people open a thread on Discourse, or that they open an issue on a relevant GitHub repository if it’s directly related to a particular repository. The goal is that Gitter has unstructured and fluid conversation that leads to more in-depth conversations in the proper Discourse/GitHub channel.
Discourse is a structured and community-focused platform for discussion. It is both discoverable and searchable, and can serve as a resource for past and present conversations around JupyterHub. We’d like all conversations that don’t directly pertain to the underlying codebase of a repository to happen in the Discourse page. This includes “how do I deploy?” questions, “best practices” questions, general discussions about enhancements, etc. The goal is that Discourse conversations result in actionable and specific issues in the repository.
The Blog / Twitter are both great ways to make a one-way connection with the outside community. They can amplify our voice, but at the cost of making it harder to have in-depth two-way communication. We use the blog and twitter for large announcements, and recommend that people go to the Discourse to engage in discussion around those announcements. As a general rule, anything that we broadcast widely via these mediums will also have a corresponding place to talk about it on the Discourse.
What should we do to accomplish this?
I think that the main changes we’d need to make for a strategy like this would be the following things:
Write up these communications guidelines somewhere in the team compass site, and include a section that links to this page in our repositories. It’d be a brief “how to participate in XXX discussions” kind of thing.
Try adjusting our issues/channels/etc practices so that we encourage people to move conversation to the right channels for their question, and get a little bit more assertive about closing issues etc that aren’t actionable in the repository.
Potential drawbacks
The main drawback that I can envision is that we come across as confrontational if we asked people to move conversations elsewhere. We run the risk of seeming dismissive if, for example, we close issues that aren’t in-scope in a repository. We should be thoughtful about how we communicate these things to community members so that we don’t rub people the wrong way.
Thoughts?
What do folks think about this? I’m happy to iterate on it with people in the discussion below. Would love to hear input from both “core team” members as well as the wider community!
I support this proposal as is, with a few nitpicks on wording.
One way to help with the “sounding dismissive” could be to have clear instructions instead of having to have a human repeat them. A bit like no one seems to argue with the CI robot over whether or not the code is correctly formatted/passes all tests.
I think if we word-smith your TL;DR bullet points we’d have a good set of four sentences we can include everywhere as guidance.
Nits: I’d add that gitter is for chatting about on and off topic things. For conversations that are meant to or Ok to be forgotten about quickly. Gitter is the coffee shop of the community. The main purpose is meeting people, hanging out, etc. I think mentioning that the community isn’t just about work but also connecting humans on a human level is important (to me).
I generally agree with @betatim. I’ve found chat bots or channel messages can help with gitter/slack/etc to give context when needed or a non-dismissive message.
I do find having too many places to go for where to connect can be a problem, but I think your breakdown is good. As an additional note, I have found Discourse to be useful to discuss various jupyter releases with relevant folks when there’s issues or one-off questions around process that are little more time sensitive for responses.
The
The goal is that Discourse conversations result in actionable and specific issues in the repository.
might want to be expanded to discuss issues in the project – there are many issues that aren’t clearly tied to the repository changes but might be usability or how-do-I style inquiries that can be searchable. This seems to imply only code issues will be discussed.
Ah that’s a good point about “actionable…” language in the description. I think what I wanted to convey there is that Discourse should be a place for more generic or unstructured conversation, and as the community identifies things that are explicitly actionable, those should be converted into issues in the repository and further conversation on that topics should be done in the respective repository.
Do you think that makes sense? If so we can change the wording to clarify!
I’d second @MSeal’s point about discourse. I’d treat discourse as the “default option” for when you can’t work out where something should go.
One thing we should ponder related to “too many places” is cross posting. Should it be done (twitter/blog posts link back to discourse) or should it not be done (GitHub issue to link/alert to a discussion on discourse)?
Addition of relevance for users of discourse I think is to clarify that topics can be moved around etc, so that fear of “did i post this in the right category” becomes less problematic - this is based from experience of discourse, it is/was a common reason to hesitate posting something.
And, related, the Plugins of considerations topic has some discussion about plugins that could be of use, or could end up cluttering things that work out good enough ^^
I think this is a nice path forward, and agree with everything that was said. GitHub also allow some canned responses, so we can easily have a pre-made response that can be easily posted.
If the concern that redirect should be posted by a bot, we can figure that out with GitHub action and have something like on_label(“move to discourse”) then post_comment(“We believe this question is better suited for discourse…”).
One thing that may turn things easier is trying to find a way to link Github Issues and Discourse topics. This could avoid duplication or bad feelings because an issue was closed.
I like the idea of bots helping managing the flow of information to where it belongs as well I think @carreau idea of label ‘should go to discourse’ is awesome
Finally, I totally agree with Gitter be a place for quick conversations. My fear is that people will tend to get questions answered there because is easier and faster.
I’ve learned that you can track categories, sub-categories, and tags — the new part was tags that I thought I could not track before.
Based on this I’m thinking perhaps we can create a tag for each repo and then add tags to questions, and allow maintainers to follow the tags=repos they want to give some love to?
Then my next question is: should we start gently enforcing this?
E.g., there are a ton of question on the z2jh repository that are basically just configuration question, very few will result in a change to the z2jh codebase. A goal of this post was to codify what kind of communication goes where, with the goal that we can eventually start nudging people in the right direction (e.g. going into those issues and recommending they discuss general “how do I configure X” questions in the Discourse rather than in GH issues.
Most effort but also best way to make people not mad would be a bot that copies the 1st post of an issue to here (q&a) if the issue gets a “support” label (by a human). And post a closing comment into the issue pointing to the new thread.
There is also a chance someone scratched that itch already.
On new issues that look like they should be here I’ve been posting a canned response telling people and asking if it would be Ok to move here. So far people seemed to find that Ok.
For repo2docker I made a PR this morning https://github.com/jupyter/repo2docker/pull/654 that introduces issue templates and as part of it made one for “support questions” which tells you “don’t post here go to discourse instead”. If we merge this I think it’ll deal with all new issues.
TL;DR: I think we should start sticking to these guidelines.
oh nice, I hadn’t noticed that PR yet, that’s great. (I wonder if we could try using a default template for this kinda thing across all repos in an org)
I think