Popularising "team-compass" repos

[betatim]

Team-compass repos.

Several years ago the JupyterHub team created a team-compass repository. The goal of the repo is to provide a place for "team interaction, syncing, and handling meeting notes across the JupyterHub ecosystem".

The point of this issue is that I think more projects would benefit from having a team-compass. The outcome of working on this would be a SPEC and other material explaining the idea, give advice, etc to popularise the idea.

We use the repo to talk about topics from "reduced availability", over "should we use pre-commit for all repos?", "coordinating outreachy work" and "is self-merging your PRs Ok?". But I think the best way to get a feeling is for people to browse the repo a bit.

Having a place like this creates a place to talk about things that are more about how to work together, than doing the work (which is more appropriate to discuss in the actual project repo).

The structure is popular and since a few years ago most of the other parts of Project Jupyter have adopted them.

It would be interesting to hear what other projects do and find out if there is something worth recommending to the wider community.

[tylerjereddy]

NumPy and SciPy have https://github.com/numpy/archive and https://github.com/scipy/archive, respectively.

They are probably a bit more static (mostly meeting notes and project presentations/assets/logos) than the interactive things you describe. NumPy and SciPy both use Slack as well though, so not sure how they'd respond to "yet another medium" type of thing. Anyway, I don't have an opinion on it, just sharing what they tend to do for part of what you describe.

[lagru]

scikit-image follows a similar approach: we recently renamed our meeting notes repo to scikit-image/skimage-archive. For more general / meta discussions we use https://discuss.scientific-python.org, and for more direct communication, e.g. on Outreachy, I'd say our Zulip server and Discord have been popular.

[betatim]

The reason I posted this and think it is an interesting thing to work on is to find out what others do, what the shared elements are, what shared gains and pains are, etc.

I'm a fan of having three different tools for three different needs of communication: "use a chat for things that if everyone forgets we talked about this in 24h it isn't a problem", "use a forum style tool for topics where the discussion might last a few days to weeks" and "write a document for things that will still be relevant in months or years". I think for jupyterhub the team-compass repo served to fill the needs of the last two steps. Gitter/Matrix is the chat tool used by JupyerHub.

The actual concrete tool used to implement each of the three tiers is probably less important than differentiating between them.

I think another useful, or maybe the most useful, thing I learnt from this "team-compass" approach is that it gives a venue that is explicitly about "team building". It is a bit like "community building" but focussed on creating a team out of the main maintainers. There is a lot of similarity between the two topics but they are different as well. A key thing I'd like to pass on is how useful it is to invest in this "maintainer team building", especially if you start right at the beginning. For example establishing that it is normal to post about your great idea first and soliciting feedback about it before you go off an work on it is useful for later in the projects life when there are more people involved/the group has become more diverse/there are important things to decide. You want to start training your group decision making muscle long before you need it to lift a big, hairy, controversial topic.

A lot of these things might sound like "trivialities" but so is setting up automated tests and CI. In both cases we all benefit a lot from having a template to copy though :D

[drammock]

three different tools for three different needs of communication: "use a chat for things that if everyone forgets we talked about this in 24h it isn't a problem", "use a forum style tool for topics where the discussion might last a few days to weeks" and "write a document for things that will still be relevant in months or years"

I really like this framing. But it kind of alternates between "how long will the discussion last" and "for how long will the discussion be relevant". (Not sure what the significance of that observation though... It is reminiscent of the "four kinds of documentation" diagram and makes me wonder if each quadrant needs it's own tool, but then I realized that the "slow discussion + short relevance" quadrant may not actually arise much).

FWIW here's what mne-python does: discord voice channels for live office hours, dev meetings, and sprints. Discord text channels (devs only) for things like "tomorrow's agenda" or "who here is knowledgeable about...". Discourse for user or contributor support questions (also announcements and job postings). GitHub wiki for dev tasks (how to cut a release) and things that change often (gsoc project ideas). Everything else end up in our built docs I guess, or else not written down anywhere.

[betatim]

makes me wonder if each quadrant needs it's own tool

I'm normally not a fan of tool explosion, but ... threads in slack are much less good than threads in something like discourse (the forum software). At the same time discourse is pretty terrible at being a real time chat. So I guess I'm settling at "maybe consolidate the number of platforms you use, but probably you need a different tool for each quadrant (even if there are only four)". The main reason for that is that different platforms are harder to integrate with each other. For example cross linking issues and PRs is easy if they are all on the GitHub platform, but harder to do between Slack and GitHub. It isn't impossible (there are integrations) but it adds friction and maintenance burden.

I realized that the "slow discussion + short relevance" quadrant may not actually arise much

But all good management consulting slides have quadrants. So I think we will have to introduce this "slow speed and short relevance" category to everyone and tell them they need it. It could be "memes that get posted in #random". It is slow because memes build on memes, yet the lolz only last for a short time before the new memes come :D

[drammock]

threads in slack are much less good than threads in something like discourse

agreed.

At the same time discourse is pretty terrible at being a real time chat.

Yep.

consolidate the number of platforms you use

Definitely.

but probably you need a different tool for each quadrant

I'm starting to come around to the idea that you could get away with just 2: Discord and GitHub.

• One GitHub repo (call it user-support) possibly utilizing the "GitHub discussions" feature, might be good enough as a replacement for a Discourse Forum. It's not quite as gamified / might not incentivize users answering each others' questions quite as well as Discourse does, but it is search-engine indexed (crucial for user support IMO) and it might even be possible to directly transfer issues from user-support to the main software repo, if it became clear that there was a genuine bug. Also the syntax highlighting would be better.
• One GitHub repo (team-compass) focused on dev team interactions / orientation / reference material.
• Discord for anything real-time (sprints, office hours, dev meetings) and for any dev communications that need to be confidential (CoC committee?) or where (near-)real-time chat is clearly the better choice than an asynchronous team-compass discussion.

Aside: at MNE-Python we've been struggling with how best to use Discord because some users really want to ask support questions there. We've bent over backwards to explain why we don't want to do that (not searchable, Discord thread functionality not great, etc), but we still get messages like this one:

hello, I recognize that people are being bounced to the mne.discourse.group but I was hoping to just chat with some people briefly before I make posts on a forum. I'm not even sure if MNE is what I need, and my main mode of online communication is through Discord, so I was hoping I could get a little bit of information from here. [...] I hope to not be bounced to a forum yet. I'm not prepared to make a forum post given that we are only just starting out with this idea and I'm just trying to gauge the avenues that I can take to try to make this happen, to try to gauge if MNE is worth exploring for this purpose or if I'm way off.

I'd be interested to hear if anyone else encounters this or has any opinions / advice.

[tylerjereddy]

I'm starting to come around to the idea that you could get away with just 2: Discord and GitHub.

Note that Discord is hard-blocked by US National Labs (or at least Los Alamos), perhaps because it has a microphone-related component, or maybe for other security reasons. I don't think you can make a decision based on that since things are super-restrictive for us anyway, but just making you aware of it.

[jpivarski]

More generically, "just 2" is a real-time chat (such as Discord) and long-term, long-form messages (such as GitHub Discussions or Discourse).

For real-time chat, we've been using Gitter in Scikit-HEP: https://app.gitter.im/#/room/#Scikit-HEP_community:gitter.im

The technology isn't great (a little flaky, particularly hard to make it know that you've already read a message). The thing that we like about it is that it's easy for people to get an account and start talking (unlike Slack, which requires an invitation). I think it accepts GitHub, GitLab, and one other, maybe Google. We were considering a move to Discord because the technology is better, it's also easy to get an account or at least is sufficiently well-known, and maybe we would get more feedback on Discord because maybe the people are already there.

However, the fact that Los Alamos (and maybe other national labs) is blocked from Discord is adds a -1 to that idea.

[hoechenberger]

Discord is also blocked in CEA/NeuroSpin in France, hence our colleagues there could never join MNE-Python office hours.

[betatim]

I think it makes sense to collect the different options that people use for each category and list the pros and cons of them. That way projects can make their own choice. Trying to pick something for everyone to use seems like it would lead to bike shedding and less useful than giving people the information about the pros and cons.

---

If people repeatedly ask the same question (in the chat) I'd take it as a hint that they can't find the information they are looking for. Maybe create a page that answers this repeated question, or if it already exists make the page easier to find or tweak the content? The vast majority of people ask questions because they can't find what they are looking for or don't realise that they found the answer to their question.

[drammock]

If people repeatedly ask the same question (in the chat) I'd take it as a hint that they can't find the information they are looking for.

I think I didn't explain myself well. It's not the same question over and over; it's different questions from different people, almost all of whom (1) don't read the "channel purpose" at the top of the screen, (2) don't read the "pinned messages" that also explain our no-support-in-this-channel policy, and (3) don't look even a couple messages back to see what's been said recently (i.e., a repetition of our policy and its rationale). (The quoted post above was the exception --- someone who clearly did get the message that questions belong on the forum but was resistant to that policy).

That said, if I think of "the relevant info" not as the answer to each specific question, but rather as "where do questions go?" then clearly you're correct that most folks are not finding that information. I'll have to poke around in Discord to see if there are ways to foreground that info more prominently.

[juanis2112]

Hackmd link for the summit: https://hackmd.io/MmbP4VTATyG129_U56xdJQ