Forums ( operation protocol operation protocol

author: @raul
version: r1, 2018-04-04

After configuring the discourse instance and loading an initial set of discussion topics, it’s time to launch!

This document defines motivation and operation protocols for the forum. It’s a living document, and we’ll keep updating it as we make discoveries.


Why do we need this?

  1. With over 150+ repos, the libp2p organisation is a Github labyrinth. It’s not easy for users to find the right place to post an enquiry.

  2. Not everybody watches all repos, therefore not everybody gets notified of issues and enquiries posted across the hundreds of repos we have (so lucky). This makes people miss conversations they’re interested in.

  3. People tend to take Github issues as a communication channel with maintainers, not with an open community. This, coupled with (2), makes Github issues unproductive for huddling and forming a community.

    • libp2p is growing rapidly, and a hub-and-spoke model will not scale.
    • The hub-and-spoke model is not a protege for an open, fluid community like the one we want to build.
    • We want people to get together, share ideas, answer each other’s questions, remove ourselves as a bottleneck, discover mutual interests,
      start hacking together.
    • Github is non-optimal for that kind of social angle.
  4. Note that we still want to keep code and technical discussions in Github.

    • It’s perfectly valid to ask a user on a forum to open an issue in Github, referencing the Discourse topic as a carry over.
    • And vice versa: usage questions, “how does this work”, etc. go in Discourse; feel free to ask the user to move the conversation over.
    • It’s a fine line, and we don’t want to define hard rules of what goes in Github and Discourse.
    • Let’s use common sense and we’ll get it right.
  5. We need a venue to announce things to the community, solicit feedback, etc. For example, we recently switched to gomod and we had no place to announce it. Not all users watch a particular repo, so a Github issue wouldn’t have worked.

There are more reasons I’m sure I’m leaving behind.

Instructions for libp2p contributors

  1. Please register now, if you haven’t done so:
  2. Go into your preferences > emails > enable ‘mailing list mode’ at the bottom.
  3. Engage!

About (3): On a daily basis, we speak over IRC (and some of us over Slack),
but those conversations are ephemeral. Let’s take them to Discourse so that
the community can benefit!

When you think of a question that you would’ve otherwise asked on IRC or Slack, post it on Discourse, and then ping the appropriate people via the side-channel to usher them into the conversation.

That way we kill two birds with one planet :penguin::penguin::comet:. We create a knowledge base for the community, while we answer our own questions. Simple and effective!

We are trusting everybody to collaborate in this process. However, in case self-drive is not sufficient, you will have a general steward and a category steward prodding you :ghost:

Read on.

Introducing the general steward

We gotta make sure to stay on top of the forum, keep it active, watch that users get answers, especially in the first weeks while it takes off.

Somebody needs to own this, and I’m nominating @yusef to be the general steward and peacemaker of the forum.

If you’d like to support Yusef, please let us know.

Over time, we’ll reevaluate if we need more cooks in the kitchen (if it gets too busy). For now I expect this will take no more than 30 min/day.

Responsibilities of the general steward

This is a non-comprehensive list; feel free to add more items.

  • Ensures topics are well-attended to in a timely fashion.
    • For this first phase, it’s super critical to answer ASAP. We want users to find value in the forum immediately. Nothing is more demotivating than spending time crafting a post, only to see a tumbleweed roll by.
    • This does not mean answering. General rule is: if you can answer in less than 5 minutes (and nobody has gotten to it before), do so.
    • If not, mention the right person in a reply, and pull them in to collaborate. Then go and pester them through Slack or IRC, or whichever side-channel you use to interact with that person.
    • We gradually need to instil the habit of helping our users; the aim is for people to monitor the forums it won’t happen overnight. It’ll require nudging.
    • If the people you ping seem unresponsive or uncollaborative, seek help from the tech lead (@raul) or the project lead (@mike).
  • Acts as a peacemaker, should conflicts arise.
  • Applies kaizen: continuous improvement. Proposes changes to structure, forums, settings, etc. where appropriate.
  • Is continuously on the lookout for things to post on the forums to strengthen the collective brain. Scouts for content.
    • When something floats by on #libp2p Slack, IRC, Github, Twitter, etc. that’s worthy of posting in the forum, they ask the poster to do so.
    • Finds ways to incorporate the usage and monitoring of this shiny discussion form in the day-to-day mental and work processes of the team and community.
    • Frequently prompts people: “how would you feel about posting this in the forum?”.

Introducing category stewards

The responsibilities of a category steward hatwearer are the same as for the general steward, but scoped to a particular forum category you have taken ownership of.

I’ve already spoken to a few category stewards, and got them to accept before nominating them:

  • Users & developers / Rust: @tomaka.
  • Users & developers / js: @jacobheun.
  • Users & developers / go: @yusef.
  • Users & developers / python: @zixuanzh.
  • Implementers & contributors: TBD (@yusef for now).
  • Research and paper discussions: TBD (@yusef for now).
  • Ecosystem and Community: @raulk.

Let’s make this a success!


Reach out to @raul.


Awesome, thanks for posting this!

I just want to mention that everyone should feel free to help me figure out what general stewardship means as we go. Raúl’s list seems like a good start and lays out the right mindset. If anyone has suggestions or sees things develop that they want to discuss with me, please hit me up and / or start a topic about it so we can figure out ways to make this place awesome.

1 Like