/collaboration-guides

some guidelines to make remote collaboration easier

Creative Commons Attribution Share Alike 4.0 InternationalCC-BY-SA-4.0

Guidelines for Effective Collaboration

We are a remote team, therefore effective communication is one of the most important foundations on which we build our technology and our company. Below you will find a thorough guide to enable your work and empower your teammates to get their stuff done, while keeping interruptions to a minimum. These guidelines apply to Ride employees and consultants who work under the Engineering Team

What to do if I need help

If you need something, keep in mind that others have a job to do as well. Before reaching out, ask yourself:

  • has this been asked before?
  • Start by searching in github, email, or dropbox documentation, slack history - invest at least 2 minutes in each.
  • Is this information for me only, or could other people benefit from it? (to determine if private message, or public forum like gh, etc)
  • Is this information sensitive?
    • i.e. keys, passwords, customer personal information
    • don't share these via email or other unsafe means.
    • passwords go in 1password, engineering vault
  • is it urgent?
    • urgent means, something needs to be done in the next ten minutes.
    • if it can wait 1 or two hours, it is not urgent
  • Am I trying to do #lazyweb?

Preferred communication methods

Sometimes it's easier to look for other people who already possess certain information, but in many cases these same people are trying to concentrate in their day to day work. If after going through the above questions you still need to reach out to someone, start going down the following list of preferred communication methods in increasing urgency order:

  • github issue, so information can be shared
  • if people outside of engineering are involved, email
  • slack
    • keep in mind your messages may be lost in history
    • don't abuse @channel, or @here or other commands because people stop paying attention
  • sms, if urgent
    • you can generally find a person's phone number in the slack directory
    • is your phone in said directory yet?
  • if in the same location, is urgent and it warrants interruption, go straight to the person
  • if the sky is falling, call cell
  • if medical emergency, call 911

If someone reaches out for help

  • respond patiently
    • expect said person has followed the above process before they reached out to you
    • be patient
  • excercise good time management
    • If you can't get to it at the moment, say so. "sorry john, I can't help you right now, can this wait a couple hours?"
    • The only person who has to respond to any question in less than an hour is @buritica
  • assess if the other person is blocked
    • Must they solve this in less than two hours?
    • Are you the only person who has this information? (please document so it's easier next time)
  • It is ok to say, "I will get back to you in X mins/hours" - but stick to it
  • If you know where this information is, share the link
  • Don't use passive-aggressive language
    • as I/someone else said before/last week/hour/50 times
  • Move the conversation to a public forum so others can benefit from knowledge and there is a record for future reference.

If you notice someone in need of help

  • point them in the right direction
  • be helpful, or refrain from adding noise to the discussion
  • Don't use passive-aggressive language
    • as I/someone else said before/last week/hour/50 times

Argument or ineffective discussion etiquette over written mediums

  • If you're not involved, suggest a phonecall ☎️
  • Don't add noise, like jokes or emojis, it makes discussions worse.
  • If you are involved, ask for a call.
  • Be polite and respectful, always.
  • If you are upset, step away for a 10 minute walk and come back.
  • If you notice someone else is upset, suggest a break but don't force it.
  • Stay away from written mediums when it comes to miscommunications (no email, chat, sms).

Messaging etiquette

  • Use proper subject labels so people can quickly determine your needs from their inbox i.e., [ack], see table below
  • If you have a github issue that needs attention, send via email to the people involved and request an [ack]
  • Don't use non-specific pronouns when you need assistance
    • People assume others will take the task, so words like someone, anyone, folks, y'all are bad practice
    • Assign your request to a specific person or do it yourself, it won't get done otherwise.
    • Don't be afraid of asking others for help, but don't abuse delegation
  • Don't abuse @channel, @here, @everyone, @some_team or shorthands that notify people and interrupt
  • Use team, folks, peeps or similar non-gendered pronouns to refer to groups of people
  • If there is no github issue, there is no problem. Ask for the creation of one or make it yourself.
  • If your email/issue is longer than 2 paragraphs, use a TL;DR
  • Include just enough information.
    • Don't add information that would make something harder to process.
    • When in doubt, use Hemingway App.

Response etiquette

  • Don't abuse reply-all
  • Our default email read time is 12 hours, unless you're in support rotation where it should be less than 4 so we can cover our team-mates.
  • Act on our common list of subject labels, see table below.
  • If your message allows for a longer response time, use label modifiers like [ack-24] or [ack-48] in your subjects, meaning 24 or 48 hours
  • If you need a response in less than 4 hours, be mindful of interruptions or ask @buritica or your manager for help first
  • Any problem that needs to be solved in less than 4 hours should be handled by Engineering Support rotation

Acking

  • acking (replying to an email with ack) is an easy way to help others know we're in sync
  • where does ack come from in our team? read this
  • don't reply all

Subject Labels

label definition
ack sender requires acknowledgement within 12 hours
[broadcast] no ack needed
[action-needed] you need to do something besides reading this email
[response-needed] you need to reply with something besides ack
[xxxx-24] modifies any label to default to 24 normal hours
[xxxx-48] 2 days to reply or act upon
[xxxx-72] 3 days to reply or act upon

Availability Etiquette

The general rule is, make sure your availability is not a blocker for the team.

  • Engineering team overall should be generally available during NYC 10am - 6pm (coverage is important)
  • You are free to work on your own schedule
  • If you use your home timezone, overlap at least 4 hours and attend any necessary meetings that require you
  • If you'll be unavailable (unreachable) for 1 or more hours during 10 - 6 NYC:
    • make sure someone can cover you, or knows where to find you in case of downtime or urgent issue
    • send an email to engineering@ride informing the change with at least 24hrs notice and who is covering you
    • no need to go into details about the nature of the appointment
    • add it to the Availibility Calendar
      • if I had to go to dentist: buritica - off the grid - 1hr
  • If you'll be traveling, working remote, or taking time off:
    • make sure someone can cover you, or knows where to find you in case of downtime or urgent issue
    • send an email to engineering@ride at least 1 week in advance, and where to find you in case of downtime or urgent issue
    • add it to the Availibility Calendar
      • if I would be working from a city that is not my base, during the NYC timezone: buritica - remote - atlanta
      • if I would be working remote, sticking to a different timezone: buritica - remote - unavailable due to timezone
      • if I am taking time off: buritica - off-the-grid
      • if I am taking a flight during 10 - 6: buritica - NYC > BOG

What should I do if someone is not following these guidelines?

  • assume it's not intentional
  • if it's the first time it happens, you may remind them how we prefer to work by pointing them to this guide privately
  • if you don't feel comfortable with the above, talk to your manager who will help you find a solution
  • if you don't feel comfortable with the above, you may bring it up to another manager with appropiate context

Final comments

Since there is a direct relationship between how we communicate and how we perform as a team, these guidelines aim to make ourselves better as a team, while we build excellent software and products. This document is open for discussion and your input is encouraged so we can grow together.