Skip to content
This repository has been archived by the owner on Oct 22, 2020. It is now read-only.

Latest commit

 

History

History
132 lines (112 loc) · 16.8 KB

communication.md

File metadata and controls

132 lines (112 loc) · 16.8 KB
Raw

☎️ COMMUNICATION

We're a distributed, remote-first team where people are allowed and encouraged to work remotely without the fear of missing out. For this, we use asynchronous communication and are as open as we can be by communicating through public issues, chat channels, and placing an emphasis on ensuring that conclusions of offline conversations are written down. These communication guidelines are meant to facilitate smooth communication in an ever-growing remote-first team.

Internal Communication

  1. All written communication happens in Italian (we should communicate in English but we're not there yet). However we should strive to write as much technical documentation in English as possible.
  2. Use asynchronous communication when possible (stories/email/Slack).
  3. Stories are preferred over email, email is preferred over Slack, and people should be able to do their work without getting interrupted by chat.
  4. To use email instead of chat it is OK to send an internal email that contains only a short message, similar as you would use in chat. Save time by not including a salutation like 'Hi Emma,' and first write the subject of the email which you copy and paste into the body. You are not expected to be available all the time. It is perfectly fine not to respond to emails and chat mentions until your planned work hours.
  5. Sometimes synchronous communication is the better option, but do not default to it. For example, a video call can clear things up quickly when you are blocked. See the guidelines on video chats for more detail.
  6. It is very OK to ask as many questions as you have, but ask them so many people can answer them and many people see the answer (so use stories or public chat channels instead of private messages or one-on-one emails) and make sure you document the answers.
  7. If you mention something (a pull request, story, commit, web page, comment, etc.) please include a link to it.
  8. All project data should be shareable by default. Don't use a local text file but rather leave comments on a story or in a shared Google doc.
  9. It is OK to bring an issue to someone's attention with a CC ("cc @user"), but CCs alone are not enough if specific action is needed from someone. The mentioned user may read the issue and take no further action. If you need something, please explicitly communicate your need along with @ mentioning who you need it from.
  10. Avoid creating private groups for internal discussions:
    1. It's disturbing (all user in the group get notified for each message).
    2. It's not searchable.
    3. It's not shareable: there is no way to add people in the group (and this often leads to multiple groups creation).
    4. They don't have a subject, so everyone has to remember the topic of each private group based on the participants, or open the group again to read the content.
    5. History is lost when leaving the group.
  11. Use low-context communications by being explicit in your communications. We are a remote-first team. Provide as much context as possible to avoid confusion.

Email

  1. Send one email per subject as multiple items in one email will cause delays (have to respond to everything) or misses (forgot one of the items).
  2. Always reply to emails by replying to all, even when no action is needed. This lets the other person know that you received it. A thread is done when there is a single word reply, such as OK, thanks, or done.
  3. If you forward an email without other comments please add FYI (for your information), FYA (for your action), or FYJ (for your judgment). If you forward an external request with FYJ it just means the person who forwarded it will not follow up on the request and expects you to decide if you should follow up or not.
  4. Emails are asynchronous, for example, if a coworker emails you on a weekend it is fine to reply during the workweek.
  5. If an email is or has become urgent feel free to ping people via chat referencing the subject of the email.

Slack

  1. If you use Slack, please use a public channel and mention the person or group you want to reach. This ensures it is easy for other people to chime in, involve other people if needed, and learn from whatever is discussed.
  2. If you're only referring to someone, but don't actually need their attention, and want to spare them from getting notified, spell out their name normally without @ mentioning them.
  3. If the subject is of value to the wider community, consider commenting on an existing story, opening a new story or write a memo.
  4. Slack messages should be considered asynchronous communication and you should not expect an instantaneous response; you have no idea what the other person is doing.
  5. If you must send a private message, don't start a conversation with a greeting as that interrupts their work without communicating anything. If you have a quick question, just ask the question directly and the person will respond asynchronously. If you truly need to have a synchronous communication, then start by asking for that explicitly, while mentioning the subject. e.g. "I'm having trouble understanding issue #x, can we talk about it quickly?".
  6. Unless you're in an active chat, don't break up a topic into multiple messages as each one will result in a notification which can be disruptive. Use threads if you want to provide extra info to the question/comment you posted.
  7. In channels like #io-questions, threads are valuable for keeping conversations together.
  8. Feel free to send a colleague a link to these guidelines if the communication in Slack should be done asynchronously.
  9. If you are having a hard time keeping up with messages, you can update your preferences to have Slack email you all notifications. To change the setting, go to Preferences > Notifications > When I'm not active on desktop... and send me email notifications.
  10. Please avoid using @here or @channel unless this is about something urgent and important. In chat try to keep the use of keywords that mention the whole channel to a minimum. They should only be used for pings that are both urgent and important, not just important. By overusing channel mentions you make it harder to respond to personal mentions in a timely manner since people get pinged too frequently. If something is urgent and important:
    1. Use @here to notify all currently active members in the room. Please only use @here if the message is important and urgent.
    2. Use @channel to notify ALL members in the room, irrespective of away status.
  11. If something is important but not urgent - like complimenting or encouraging the entire team - use email or post in the channel without @-mentioning the team.
  12. If you agree in a message to start a video call (typically by asking "Call?") the person that didn't leave the last comment starts the call. So either respond to the "Call?" request with a video link or say "Yes" and let the other person start it. Don't say "Yes" and start a call 5 seconds later since it is likely you'll both be creating a video call link at the same time.
  13. The usage of ChatBots for integrations can sometimes depend upon the name of the channel. You should consult the channel about such integrations before changing the name of commonly used / popular channels in order to avoid inadvertently breaking integrations.
  14. If you are aware that your teammate is on vacation, avoid mentioning them in a high volume channel. It will be difficult to find the information or question when they return. If you need to ensure they refer back to the thread, ensure to send them a link to the relevant Slack message through a direct message.
  15. It's not rude to leave a channel. When you've had your questions answered or are no longer interested, feel free to leave the channel so it won't distract you anymore.
  16. Learn about common channels and channel-naming conventions.

Slack Channels

The IO team is part of the Developers Italia Slack organization. To join our Slack channels you'll need to create an account on the Slack organization. The Slack organization is open and anybody can join it.

The IO team hangs out in the following channels:

  • #io-dev - this is where most development activity happens, join this channel if you're actively contributing to the project
  • #io-infra - activity about the infrastructure that keeps IO up
  • #io-handbook - this is where we discuss about this handbook and propose changes
  • #io-questions - general questions about the project, this is a good place to ask questions about integrating with IO
  • #io-random - random discussions, sharing of interesting articles, chitchat
  • #io-status - this is populated by bots, sharing various alerts and status reports
  • #io-ci - this is populated by bots, sharing the status of our CI builds
  • #io-github - this is populated by bots, sharing the status of our Github activity

Weekly Review and Planning calls

  1. Every Tuesday at 2pm CET we have the product review and planning call.
  2. We use Google Hangout
  3. It is OK to talk over people or interrupt people to ask questions, cheer for them or show your compassion. This encourages more conversation and feedback in the call. Also see the interruption item in the video calls below.
  4. The sprint planning and review call is structured as follows:
    1. We start with some greetings and chitchat while we wait for all the participants to join (max 5 minutes).
    2. We start reviewing each story in the the backlog from the top (first the work in progress stories, then the unstarted stories).
    3. Since the backlog is looooong and we don't have all day, we try to keep the discussion of each story short (usually under 5 minutes) - this is also as a form of respect to the participants' time as the discussion of a single story usually happens between 2-3 people (agains 10+ participating in the call).
    4. If a story is labeled on-hold we skip it, unless somebody has some reason to un-hold it.
    5. If the story is still in progress, the story owner updates the rest of the team about the status. The story gets updated in case some blockers emerge.
    6. Stories get updated or new stories get created right away in case the scope of an existing story is incomplete.
    7. Any decision or clarification about a story gets written down in a comment for that story for future reference (also because there may be some team member missing during the call and they would miss this information if we don't write it down).
    8. If a story has been delivered and not yet accepted or rejected, if it's possible to verify its status quickly, we do it by accepting or rejecting it right away.
    9. We try to keep technical discussions about a story outside this call (either in the story comments, in its PR comments or with a dedicated call).
    10. When we completed reviewing the current stories, we proceed reviewing the topmost unstarted stories (usually around 10-15, depending on how many people will be contributing to the next sprint).
    11. If there is a clear owner for a story we assign it right away, or else it's up to anybody whishing to work on that story to assign it to himself.
    12. During the review of unstarted stories we try also to reorder the stories based on the updated priorities (this happens frequently when we have new releases or some critical bugs emerge).
    13. At the end of the review there may be the need to discuss further about a specific story or issue, in this case all participants that are not involved in the discussion can drop off the call.
    14. The review and planning that happens during this call is not set in stone, during the following days we may reprioritize or add stories if some critical issue comes up or if we find out that some planned story can't be worked on due to a blocker.

Video Calls

  1. Use video calls if you find yourself going back and forth in an issue/via email or over chat. Rule of thumb: if you have gone back and forth 3 times, it's time for a video call.
  2. Sometimes it's better to not have a video call. Consider these tradeoffs:
    1. It is difficult (or impossible) to multi-task in a video call.
    2. It may be more efficient to have an async conversation in an issue, depending on the topic.
    3. A video call is limited in time: a conversation in an issue can start or stop at any time, whenever there's interest. It is async.
    4. A video call is limited in people: you can invite anybody into an async conversation at any time in an issue. You don't have to know who are the relevant parties ahead of time. Everyone can contribute at any time. A video call is limited to invited attendees (and those who have accepted).
    5. You can easily "promote" an async conversation from an issue to a video call, as needed. The reverse is harder. So there is lower risk to start with an async conversation.
    6. For a newcomer to the conversation, it's easier and more efficient to parse an issue, than to read a video transcript or watch it.
    7. Conversations in issues and stories are easily searchable. Video calls are not.
  3. Having pets, children, significant others, friends, and family visible during video chats is encouraged. If they are human, ask them to wave at your remote team member to say "Hi".
  4. We prefer Google Hangout.
  5. For meetings that are scheduled via calendar there is automatically a Google Hangouts URL added. This is the meeting place. Having a URL in advance is much more reliable than trying to call via Hangouts as the meeting start.
  6. Use a headset with a microphone, Apple Earpods are great. Do not use computer speakers, they cause an echo. Do not use your computer microphone, it accentuates background noise. If you want to use your Bose headphones that is fine but please ensure the microphone is active.
  7. In video calls everyone should own a camera and a headset, even when they are in the same room. This helps seeing and hearing the person that is talking.
  8. It also allows people to easily talk and mute themselves. Using a headset also prevents echo. You wouldn't share an office seat together, so don't share your virtual seat at the table.
  9. Please speak up asap when someone on the call hasn't muted their mic to avoid disturbances to the person speaking.
  10. We start on time and do not wait for people. People are expected to join no later than the scheduled minute of the meeting (before :01 if it is scheduled for :00). The question 'is everyone here' is not needed.
  11. It feels rude in video calls to interrupt people. This is because the latency causes you to talk over the speaker for longer than during an in-person meeting. We should not be discouraged by this, the questions and context provided by interruptions are valuable. This is a situation where we have to do something counter-intuitive to make all-remote meetings work. Everyone is encouraged to interrupt the speaker in a video call to ask a question or offer context. We want everyone to contribute instead of a monologue.
  12. We try to end on the scheduled time. It might feel rude to end a meeting, but you're actually allowing all attendees to be on time for their next meeting.

Video Recordings

  1. If possible, try to record every video call that can be useful to other colleagues (es. during the onboarding process)
  2. Since recoding a video call has zero cost, default to recording unless you're going to talk about sensitive or personal topics
  3. When recording a video call with external participants, always ask for consent after starting the recording so that the consent gets recorded
  4. If you're going to share code, increase the font size to make it readable at low resolution (18+ should work)
  5. When recording a screen share with Google Meet, "pin" the video stream so that it takes 100% of the video, or else it gets rescaled to make space for the speaker avatar
  6. Be careful not to show secrets, password and api keys when you share your screen

Writing Style Guidelines

  1. We use American English as the standard written language.
  2. Do not use rich text, it makes it hard to copy/paste. Use Markdown for things stored in git. In Google Docs use "Normal text" using the style/heading/formatting dropdown and paste without formatting.
  3. If you have multiple points in a comment or email, please number them to make replies easier.
  4. When you reference an issue, pull request, comment, commit, page, doc, etc. and you have the URL available please paste that in.
  5. Always write IO with a capitalized I and O, even when writing IO.italia.it.
  6. If an email needs a response, write the answer at the top of it.
  7. Do not use acronyms when you can avoid it as you can't assume people know what you are talking about. Example: instead of MR, write merge request.
  8. When creating lists, use numbered lists instead of bullet lists, so points are easier to reference during a discussion.