zulip/docs/contributing/how-we-communicate.md

How we communicate

The primary communication forum for the Zulip community is the Zulip server hosted at chat.zulip.org. If you are not familiar with it, start by reading the Zulip development community section of the contributing guide. The guidelines here also apply to how we communicate on GitHub issues and pull requests, but other pages in this section go into greater detail about expectations that are specific to pull requests.

We are deeply committed to maintaining a respectful, collaborative atmosphere in across all interactions in the Zulip community. To get a feel for what that means to us, please review the code of conduct for our community.

Beyond that, the following guidelines should help you communicate effectively to express your perspective, and support and encourage other participants in the community. By incorporating these patterns of behavior, we'll be able to reach better decisions as a group, and learn and have fun along the way.

Providing suggestions and feedback

• Aim to present your feedback precisely, with reasoning, and in as objective a fashion as you can manage. E.g., “This button really jumps out at me in a way that’s distracting; maybe it’s because of the color has a higher contrast than the surrounding components?” is better than, “Can we make that color less dark?”.

• Clarify your feedback if there are follow-up questions or points of confusion. However, avoid simply repeating the same points, as it does not move us closer to making the best decisions we can.

• When relevant, highlight information you have beyond your personal opinion. E.g., “I moderate a community, and often have to answer questions about how this works,” is more helpful than, “This is confusing.”

• In addition to offering constructive feedback, call out specific things that someone is doing well. This helps folks feel good about their work, and also helps them learn. E.g., “I particularly like the test you added, because...”

• When asking someone to do something, explain the reasoning behind your request. This is more motivating, and educates folks on what to do next time.

• If you are not certain about a suggestion you're making, it often works well to frame it as a question. E.g., “Would this be clearer if we...?” or “Could we...?”.

• Invite others to disagree or contribute additional thoughts, especially if you might be considered an authority in the area being discussed. When more folks feel comfortable speaking up, we are better able to identify problems and fine-tune solutions.

Handling disagreements

• Always treat other participants in the discussion with respect, regardless of whether you agree with their ideas. Ad hominem attacks are never appropriate.

• Approach discussions with a perspective of curiosity. If someone has expressed an opinion you find odd or surprising, ask them to explain in more detail where they are coming from.

• If you think someone is factually mistaken, consider how they might have reached their conclusion, and aim to get to a shared understanding. E.g.:

  • “I wasn't able to replicate this -- is it possible you are on an old Zulip server?”, rather than “This bug report is wrong.”
  • “Using this function won't work here, because...” instead of “That's the wrong function.”

• If you disagree with someone on the core team, the best way to make progress is usually to state your opinions and reasoning clearly and respectfully, and then let the other core team members catch up on the conversation. Other project members may find your argument persuasive, and may have ideas that address your concerns.

Expressing your appreciation

There are many ways to contribute to the Zulip community, and it's important to express our appreciation for all the different ways in which folks jump in to help. It helps motivate others, builds consensus towards decisions, and creates a more positive atmosphere in the community.

For many community participants, it takes stepping out their comfort zone to try something for the first time, such as submitting a pull request, answering a question in the development community, or suggesting a new feature. It's especially important to thank and encourage folks who are stretching themselves to try something new.

• Remember to say “thanks” when responding to a question or suggestion. E.g.:

  • “Thanks for the report! ... ” when someone reports a bug.
  • “Thanks for reviewing my PR! ... ”

• Express your appreciation for the work that went into a pull request, even when it turns out that the approach taken in the PR is not successful. E.g., “Thanks for working on this! ... ”

• Try especially hard to express your appreciation for others' contributions, effort and ideas when you are also providing negative (constructive) feedback on their work.

• You can use a variety of channels to express your appreciation. A comment directly in a Zulip thread or on a pull request is often best, but in some cases you may also want to send a friendly direct message. E.g.:

  • “I've noticed that you've been answering lots of questions in #development help lately. Thanks so much for doing that!”
  • “Thanks for moving those messages into a new topic -- the discussion was getting really tangled!”

• Sometimes a quick emoji reaction can help someone feel that their work is appreciated. 🎉

• Look over the message you just sent. Did you forget to say “thanks”? It's easy to edit your message, or send a quick follow-up.