We're an online-only organisation that allows people to work from almost anywhere in the world. It's important for us to practice clear communication in ways that help us stay connected and work more efficiently.
To accomplish this, we use asynchronous communication as a starting point and stay as open and transparent as we can by communicating through public issues, merge requests.
We also place an emphasis on ensuring that conclusions of offline conversations are written down. When we go back and forth three times, we jump on a synchronous video call.
We communicate respectfully and professionally at all times.
Assume Positive Intent. Always begin with a position of positivity and grace.
Kindness Matters. You are looking at a screen, but you are really talking to a person. If you wouldn't say it to a person's face, don't send it to them in a text message.
Express Your Thoughts. We live in different locations and often have very different perspectives. We want to know your thoughts, opinions, and feelings on things.
Own It. If you say it or type it, own it. If it hurts the organisation or an individual, even unintentionally, we encourage you to look at things from other points of view and apologise easily.
Be a Role Model of our Values.
Feedback is Essential. It is difficult to know what is appropriate in every one of our team members countries. We encourage team members to give feedback and receive feedback in a considerate way.
Don't Underestimate a 1:1. Asynchronous communication (e.g., via text) is helpful and necessary. In some cases (e.g., to clarify misunderstandings) it can be much more effective to jump on a video call.
Always Adhere to our Anti-Harassment Policy and Code of Conduct. Everyone should be comfortable in their work environment.
Focus on what we can directly influence. There are many factors we can't directly influence and we should avoid spending time discussing those things.
Embracing asynchronous communication and learning to use it effectively requires a mental shift. This can feel unusual or even uncomfortable for those who come from a colocated environment, where in-person meetings and communiques are the norm.
If you see something that concerns you in Messaging, Issues, Merge Requests, Video, Emails or any other forum, we encourage you to respectfully say something directly to the individual in a 1:1 format. If you are not comfortable reaching out to the individual directly, please reach out to your direct manager to discuss.
Key practices to consider during any meeting are listed below.
Video Calls - If this is your first time meeting a customer/prospect/partner/etc., turn on your camera when you login. This will help to make the customer/prospect feel more comfortable as they are certain your undivided attention is geared towards them.
Agenda - Always have an agenda prepared and ready to go. Share this with your audience. Make sure that everything on the agenda is accurate and ask if there’s anything missing that needs to be addressed during this call or for the future. When there is no agenda, it translates to you not caring.
70/30 Rule - Ask open ended questions that leave the audience talking 70% of the time, while you are talking 30% of the time. Please note that this varies based on the type of meeting that you are conducting. Be conscious of what questions needs to be asked and to capture those items.
Take Notes - Effective note-taking is a valuable skill that will help you retain and recall any important details. Be the person who remembers all the details of your audience's needs.
Adapt to Audience Tone - Before going into the business portion of your meeting, evaluate first the tone of the audience. Adapt your tone accordingly in order to appeal to various types of personalities.
Mid-call - Half-way through the meeting, check in with your audience. Ask them what their thoughts are on the progression of this meeting and if what you're presenting is on the right track. This helps both you and the audience by re-aligning expectations and making sure the meeting is going the right direction.
Pre-Close Summary - 10 Minutes (1-hour meetings) or 5 minutes (30 minute meetings) prior to ending the call, ask the audience to build out an agenda for the next step or meeting. This helps to secure next steps and to ensure there are no balls dropped.
Post Meeting Action - Immediately write down notes and next steps and input into proper directory.
Two Block Rule - For in person meetings with external parties you should wait until you're more than two blocks from the meeting before discussing the results of the meeting. Nobody wants to hear themselves being discussed in the bathroom.
It's best practice to start a discussion where possible with a Merge Request (MR) instead of an issue. An MR is associated with a specific change that is proposed and transparent for everyone to review and openly discuss. The nature of MRs facilitate discussions around a proposed solution to a problem that is actionable. An MR is actionable, while an issue will take longer to take action on.
Always open an MR for things you are suggesting and/or proposing. Whether something is not working right or we are iterating on new internal process, it is worth opening a merge request with the minimal viable change instead of opening an issue encouraging open feedback on the problem without proposing any specific change directly. Remember, an MR also invites discussion, but it's specific to the proposed change which facilitates focused decision.
Never ask someone to create an issue when they can default to the merge request.
Starting with a Merge Request is part of Handbook First and helps ensure the handbook is up-to-date when a decision is made. It is also how we make it possible for Everyone to Contribute. This is true, not just for updating the handbook but for updating all things.
Merge Requests, by default, are non-confidential. However, for things that are not public by default please open a confidential issue with suggestions to specific changes that you are proposing. The ability to create Confidential Merge Requests is also available. When possible, consider not including sensitive information so the wider community can contribute.
Not every solution will solve the problem at hand. Keep discussions focused by defining the problem first and explaining your rationale behind the Minimal Viable Change (MVC) proposed in the MR.
Be proactive and consistent with communication on discussions that have external stakeholders such as customers. It's important to keep communication flowing to keep everyone up to date. MRs can appear stale if there aren't recent discussions and no clear definition on when another update will be provided, based on feedback. This leaves those subscribed in the dark, causing unnecessary surprise if something ends up delayed and suddenly jumps to the next milestone. It is important that MRs are closed in a timely manner through approving or rejecting the open requests.
Have a bias for action and don't aim for consensus. Every MR is a proposal, if an MRs author isn't responsive take ownership of it and complete it. Some improvement is better than none.
Cross link issues or other MRs with related conversations. E.g. if there’s a ticket that caused you to create a MR, make sure to document the MR link in the ticket and vice versa. And when approving or rejecting the MR, include reason or response from the ticket. Put the link at the top of each MR's description with a short mention of the relationship (Report, Dependency, etc.) and use one as the central one and ideally close the alternate if duplicate.
When providing links to specific lines of code relevant to the MR, always use a permalink (a link to a specific commit for the file). This ensures that the reference is still valid if the file changes. For more information, see Link to specific lines of code.
If submitting a change for a feature, update the description with the final conclusions (Why an MR was rejected or why it was approved). This makes it much easier to see the current state of an issue for everyone involved in the implementation and prevents confusion and discussion later on.
Submit the smallest item of work that makes sense. When proposing a change, submit the smallest reasonable commit, put suggestions for other enhancements in separate issues/MRs and link them. An MR can start off as only a problem description and TODO comments.
Do not leave MRs open for a long time. MRs should be actionable – stakeholders should have a clear understanding of what changed and what they are ultimately approving or rejecting.
Make a conscious effort to prioritize your work. The priority of items depends on multiple factors: Is someone waiting for the answer? What is the impact if you delay it? How many people does it affect, etc.?
When submitting a MVC, ask for feedback from your peers. For example, if you're a designer and you propose a design, ping a fellow designer to review your work. If they suggest changes, you get the opportunity to improve your design and propose an alternative MR. This promotes collaboration and advances everyone's skills.
Respond to comments within a threaded discussion. If there isn't a discussion thread yet, you can use the Reply to comment button from the comments to create one. This will prevent comments from containing many interweaves discussions with responses that are hard to follow.
If your comment or answer contains separate topics, write separate comments for each, so others can address topics independently using the Reply to comment button.
If you have received any feedback or questions on your MR, try to acknowledge comments as that's how we ensure we create an environment of belonging for all team members. Merging your MR as-is without giving an answer or any response makes the commenters feel their opinions are unheard. If you are the DRI who does not have to make a fast decision, you can choose not to change your MR, but you should acknowledge the comments or feedback, consider if they warrant a change to your MR, and say why, not just what. If there are many comments, you can choose to summarise key feedback areas and share your response at a high level. We appreciate that if you force a DRI to explain too much, you'll create incentives to ship projects under the radar. The fear of falling into a perpetual loop of explaining can derail a DRI, and cause people to defer rather than working with a bias for action. This is something we want to avoid. When fast decisions are needed, we'll have to accept that people listened to us but don't owe us an explanation to have fast decisions based on everyone's input. The goals are to be transparent and collaborative–not to lose efficiency. Not everyone will agree, but we expect all people to disagree, commit, and disagree.
Even when something is not done, share it internally so people can comment early and prevent rework.
If any follow-up actions are required on the issue after the merge request is merged (like reporting back to any customers or writing documentation), avoid auto-closing the issue.
If a project requires multiple approvals to accept your MR, feel free to assign multiple reviewers concurrently. This way the earliest available reviewer can start right away rather than being blocked by the preceding reviewer.
Consider recording a concise video or audio file outlining the merge request and uploading it to YouTube. This will make content more accessible, prevent future confusion, allow for multitasking (e.g. cooking dinner and listening to the video), and increase participation for folks who digest audio information better than visual.
Issues are useful when there isn't a specific code change that is being proposed or needed. For example, you may want to start an issue for tracking progress or for project management purposes that do not pertain to code commits. This can be particularly useful when tracking team tasks and creating issue boards. However it is still important to maintain focus when opening issues by defining a single specific topic of discussion as well as defining the desired outcome that would result in the resolution of the issue. The point is to not keep issues open-ended and to prevent issues from going stale due to lack of resolution. For example, a team member may open an issue to track the progress of a blog post with associated to-do items that need to be completed by a certain date (e.g. first draft, peer review, publish). Once the specific items are completed, the issue can successfully be closed. Below are a few things to remember when creating issues:
When closing an issue leave a comment explaining why you are closing the issue and what the MVC outcome was of the discussion (if it was implemented or not).
We keep our promises and do not make external promises without internal agreement.
Be proactive and consistent with communication on discussions that have external stakeholders such as customers. It's important to keep communication flowing to keep everyone up to date. Issues can appear stale if there aren't recent discussions and no clear definition on when another update will be provided, based on feedback. This leaves those subscribed in the dark, causing unnecessary surprise if something ends up delayed and suddenly jumps to the next milestone. It is important that issues are closed in a timely manner. One way of doing this is having the current assignee set a due date for when they will provide another update. This can be days or weeks ahead depending on the situation, prioritisation, and available capacity that we may have.
If a user suggests an enhancement, try and find an existing issue that addresses their concern, or create a new one. Ask if they'd like to elaborate on their idea in an issue to help define the first MVC via a subsequent MR.
Cross link issues or MRs with related conversations. Another example is to add "Report: " lines to the issue description with links to relevant issues and feature requests. When done, add a comment to relevant issues (and close them if you are responsible for reporting back, or reassign if you are not). This prevents internal confusion and us failing to report back to the reporters.
When cross-linking issues or MRs, include a preview of the content you are linking, to facilitate low-context communication:
Good: this would cause performance issue similar to #123456. The reader has full information on first read and can refer to the link for more.
Avoid: this would cause issue similar to #123456. The reader needs to click the link and find the relevant information among other discussion threads, before switching back to the original discussion.
When providing links to specific lines of code relevant to the issue, always use a permalink (a link to a specific commit for the file). This ensures that the reference is still valid if the file changes. For more information, see Link to specific lines of code.
Prioritise your work on issues in the current milestone.
Assign an issue to yourself as soon as you start to work on it, but not before that time. If you complete part of an issue and need someone else to take the next step, re-assign the issue to that person.
Ensure the issue title states what the desired outcome should be. For instance, for bugs make sure the issue states the desired result, not the current behaviour.
Regularly update the issue description with the latest information and its current status, especially when important decisions were made during the discussion. The issue description should be the single source of truth.
If you want someone to review an issue, do not assign them to it. Instead, @-mention them in an issue comment. Being assigned to an issue is a signal that the assignee should or intends to work on it. So you should not assign someone to an issue and mis-represent this with a false signal.
If you'd like to inform someone about an issue, or assign a task to them - do so via an issue comment not just adding them to the description. Here's why - the To Do generated when mentioning someone in an issue description provides little context to the action requested, explicitly informing them of the action via a comment ensures when they read the To Do they have more context without reading the entire issue.
Do not close an issue until it is done. It's okay to explicitly ask if everyone is on board and in agreement on how to move forward, whether to iterate, close the open issue, or create a subsequent MR to implement a MVC.
Once a feature is done, update the description to add a link to the corresponding documentation. When using a Search Engine, issues often appear before documentation pages, which makes it harder to find the relevant information about the feature.
Write issues so that they exclude private information. This way, the issue can be public. Only use confidential issues, if the issue must contain non-public information. Note: Confidential issues are accessible to all members of the project with Reporter access and above.
If the content within a public issue transitions to become what is deemed confidential, the issue may be made confidential.
If the content of a public issue draws comments that are deemed in violation of our code of conduct the issue may be locked and may undergo moderation.
In an online-only setting, where team members are empowered to live and work where they're most fulfilled, mastering asynchronous workflows is vital to avoiding dysfunction and enjoying outsized efficiencies and lifestyle flexibility. Asynchronous communication is the art of communicating and moving projects forward without the need for additional stakeholders to be available at the same time your communique is sent.
All written communication happens in English, even when sent one on one, because sometimes you need to forward an email or chat.
Use asynchronous communication when possible: merge requests (preferred) or issues.
Discussion in issues or Merge Requests is preferred over everything else. If you need a response urgently, you can message someone with a link to your comment on an issue or merge request, asking them to respond there, however be aware that they still may not see it straight away.
If you choose to 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.
You are not expected to be available all the time. There is no expectation to respond to messages outside of your planned working hours.
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.
It is very OK to ask as many questions as you have. Please ask them so many people can answer them and many people see the answer. Use issues or public chat channels instead of direct messages or one-on-one emails. If you have researched in the handbook and could not find the answer or need clarity, include the handbook link you were reviewing and state "while looking in the handbook I could not find x,y,z".
If someone sends you a handbook link they are proud that we have the answer documented, they don't mean that you should have found that yourself or that this is the complete answer, feel free to ask for clarification.
If the answer to a question isn't documented, please immediately make a merge request to add it to the handbook in a place you have looked for it. It is great for the person who answered the question to see you leading by example to ensure that question only needs to be answered once. A merge request is the best way to say thanks for help.
If you mention something (a merge request, issue, commit, webpage, comment, etc.) please include a link to it.
All company data should be shareable by default. Don't use a local text file, but rather leave comments on an issue.
When someone asks something, give back a deadline or that you did it. Answers like: 'will do', 'OK', 'it is on my todo list' are not helpful. If it is small it's better to spend 2 minutes and do the tasks so the other person can mentally forget about it. If it is large you need to figure out when you'll do it, by returning that information the other person might decide to solve it in another way if it takes too long.
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.
Avoid creating private groups for internal discussions:
Use low-context communications by being explicit in your communications. We are an online-only company, located all over the world. Provide as much context as possible to avoid confusion. Relatedly, we use ubiquitous language for communication efficiency.
When discussing concepts, be careful not to lean too much into hypotheticals. There is a tipping point in which it decreases value and no longer becomes constructive at helping everyone come into a unified decision.
Competencies are the Single Source of Truth (SSoT) framework for things we need team members to learn.
In an online-only organisation effective communication is key to exchanging knowledge, ideas, and information.
Effective communication using asynchronous communication as the starting point and staying as open and transparent as we can by communicating via text through public issues, merge requests, and messaging channels (over DMs). Placing an emphasis on ensuring that conclusions of offline conversations are written down ensuring Single Source of Truth and producing video when necessary.
Skills and behaviour of applying effective communication as a Team Member:
Skills and behaviour of applying effective communication as a People Manager:
When taking notes in an agenda, in the handbook, or on our OKRs, keep items numbered so we can refer to Item 3 or 4a. The number is not a signal of the importance or rank of the subject unless explicitly stated to be such. It is just for ease of reference.
When working on a problem or issue, communicate directly with the people you need support from rather than working through reporting lines. Direct communication with the people you need to collaborate with is more efficient than working through your manager, their manager, or another intermediary. Escalate to management if you are not getting the support you need. Remember that everyone is a manager of one and they might have to complete their own assignments and inform the reporting lines.
It is estimated that listeners will filter out or change the intended meaning of what is heard in 70% of all communications. Source.
Myths about Listening
Tips for Effective Listening
Being Assertive
There is a delicate balance between being confident enough to be assertive of personal rights and boundaries while respectful of others.
Social calls are considered an important way to foster culture while organically creating connections between team members with similar interests or hobbies.
These calls happen six times a week at varying times to ensure that team members in all timezones are able to take part (should be adopted to the actual situation).
The use of a document also serves to ensure that everyone gets a chance to contribute to the conversation.
Social call attendance is not mandatory however the sessions do serve as a great way to get to know fellow team members, take a break or (depending on your region) start the day on a fun note.
Keep conversations positive, friendly, real, and productive while adding value.
If you make a mistake, admit it. Be upfront and be quick with your correction. If you're posting to a blog, you may choose to modify an earlier post. Just make it clear that you have done so.
There can be a fine line between healthy debate and incendiary reaction. Try to frame what you write to invite differing points of view without inflaming others. You don’t need to respond to every criticism or barb. Be careful and considerate.
Assume positive intent and explicitly state the strongest plausible interpretation of what someone says before you respond, not a weaker one that's easier to criticise. Rapoport's Rules also implores you to list points of agreement and mention anything you learned.
Answer questions, thank people even if it’s just a few words. Make it a two way conversation.
Appreciate suggestions and feedback.
Don't make promises that you can't keep.
Guide users who ask for help or give a suggestion and share links.
When facing negative comment, respond patiently and treat every user as an individual, people with the strongest opinions can turn into the strongest supporters.
By default, discussions in issues and MRs are public and could include participation of wider community members. It is important to make the wider community members feel welcome participating in discussions and sharing their view.
Adhere to the Code of Conduct in all communication. Similarly, expect users to adhere to the same code when communicating with the team and the rest of the community. No one should accept being mistreated.
We use English as the standard written language.
Do not use rich text, it makes it hard to copy/paste. Use markdown to format text that is stored in a Git repository. In Google Docs use "Normal text" using the style/heading/formatting dropdown and paste without formatting.
Don't use ALL CAPS because it feels like shouting.
We use Unix style (lf) line endings, not Windows style (crlf), please ensure *.md text eol=lf is set in the repository's .gitattributes and run git config --global core.autocrlf input on your client.
Always write a paragraph on a single line. Use soft breaks ("word wrap") for readability. Don't put in a hard return at a certain character limit (e.g., 80 characters) and don't set your IDE to automatically insert hard breaks. Merge requests for the blog and handbook are very difficult to edit when hard breaks are inserted.
Do not create links like "here" or "click here". All links should have relevant anchor text that describes what they link to. Using meaningful links is important to both search engine crawlers (SEO) and accessibility for people with learning differences and/or physical disabilities. This guidance should be followed in all places links are provided, whether in the handbook, website, GoogleDocs, or any other content.
Always use ISO dates in all writing and legal documents since other formats lead to online confusion. Use yyyy-mm-dd, for example 2015-04-13, and never 04-13-2015, 13-04-2015, 2015/04/13, 20150413, 2015.04.13, nor April 13, 2015. Even if you use an unambiguous alternative format it is still harder to search for a date, sort on a date, and for other team members to know we use the ISO standard. For months use yyyy-mm, so 2018-01 for January. Refer to a year with CY18 (never with 2018) and a quarter with CY18-Q1 to prevent confusion with fiscal years and quarters. If the year is obvious from the context it is OK to use Dec 4, but not 12/4, since the ordering isn't obvious when using two numbers but when naming the month it is clear that the number of the day of the month.
Remember that not everyone is working in the same timezone; what may be morning for you is evening for someone else. Try to say 3 hours ago or 4 hours from now, or use a timestamp, including a timezone reference.
We use UTC as the timezone for engineering (for example production) and all cross-functional activities related to the monthly release.
If you have multiple points in a comment or email, please number them. Numbered lists are easier to reference during a discussion over bulleted lists.
When you reference an issue, merge request, comment, commit, page, doc, etc. and you have the URL available please paste that in.
In making URLs, always prefer hyphens to underscores, and always use lowercase.
Use inclusive and gender-neutral language in all writing.
Do not use a hyphen when writing the term "open source" except where doing so eliminates ambiguity or clumsiness.
If an email needs a response, write the answer at the top of it.
Try to use the active voice whenever possible.
Always use a single space between sentences rather than two.
Do not use acronyms when you can avoid them. Acronyms have the effect of excluding people from the conversation if they are not familiar with a particular term. Example: instead of MR, write merge request (MR). If acronyms are used, expand them at least once in the conversation or document and define them in the document using Kramdown abbreviation syntax. Alternatively, link to the definition.
We use ubiquitous language to increase communication efficiency.
This is defined in Domain-driven design as: "A language structured around the domain model and used by all team members to connect all the activities of the team with the software."
By having ubiquitous words to identify concepts we prevent confusion over what is meant, for example we refer to as a function, department, or group depending on exactly what is meant.
Make sure that domains don't overlap. If a term is ambiguous don't use it.
Make sure that projects and working groups have clear and direct names.
Keep terms to one or at most two words to prevent people from introducing ambiguity by shortening a term. When using two words make the first word unique because people tend to drop the second word more often.
Simple Language is meant to encourage everyone to simplify the language we use. We should always use the most clear, straightforward, and meaningful words possible in every conversation. Avoid using "fluff" words, jargon, or "corporate-speak" phrases that don't add value.
When you don't use Simple Language, you:
Confuse people and create a barrier for participants of your conversation.
Cause others to not speak up in a meeting because they don't understand what you're saying.
Are not inclusive of those whose first language is not English.
Do not add value with your words.
When you do use Simple Language, you:
Get work done more efficiently.
Build credibility with your audience (your team, coworker, customer, etc.).
Keep people's attention while you're speaking.
Come across more confident and knowledgable.
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).
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.
If you're sending an email to a large group of people (or a distribution list), put those recipients in BCC (rather than in the "To" field) so that a reply all won't ping hundreds of people.
If you forward an email without other comments please add FYI (for your information), FYA (for your action), or FYC (for your consideration). If you forward an external request with FYC 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, the terms comes from movie promotion to voters.
Emails are asynchronous, for example, if your manager emails you on a weekend it is fine to reply during the workweek.
If an email is or has become urgent feel free to ping people via chat referencing the subject of the email.
Where appropriate, consider using professional salutations including Hi or Hello and avoid colloquial expressions such as Hey, Oh, or Sup. Sometimes only the person's name is suitable. The level of formality should often mirror the formality from previous messages when communicating with internal team members as well as external persons.
Try to always use a person's name when starting or responding to a message, especially if there are multiple persons cc'd, so that the addressee knows you are addressing them.
Make sure all relevant letters and words that need capitalisation are capitalised, such as the start of sentences or the word "I".
Proofread your messages so that sentences are punctuated correctly, typos are fixed, and grammar is corrected. Consider using the really helpful Grammarly tool - this tool is great for both native English speakers and for those who use English as an additional language.
All messages and replies are signed with a professional send-off (ex. Best regards), your name, and your signature block.