(Community version, lightly edited, primarily to remove internal URLs and references)
This document is a quick-reference companion to the full "How GitHub Engineering communicates" document. For more details about anything noted here, as well as background/purpose and usage information, please see that full set of guidance.
Overall, the way we communicate as an Engineering organization is informed by the following principles (fully defined in the "How GitHub Engineering communicates" guidance):
- Be asynchronous first
- Write things down
- Make work visible and overcommunicate
- Prefer GitHub tools and workflows
- Embrace collaboration
- Foster a culture that values documentation maintenance
- Communicate openly, honestly, and authentically
- Strive for inclusivity
- Use emoji and animated GIFs
- Remember practicality beats purity
In brief, here's which communication channel we prefer for which purpose (further explained in the "How GitHub Engineering communicates" guidance):
Chat (e.g., Slack) is great for questions, water-cooler talk, amplifying messages communicated elsewhere, and other time-sensitive matters that are best handled semi-synchronously, but not as a primary means of critical decision making or a canonical source of truth. Unless it's sensitive, prefer public channels to private DMs. If impactful conversations do occur via chat, memorialize them on GitHub after the fact.
Repositories represent real-world projects, initiatives, and teams. They're easiest to imagine as a project's (or team's) folder. A repo contains all of the project files (including documentation), and stores each file's revision history.
Discussions are our virtual bulletin board. Post announcements, ideas, polls, open-ended questions, or whatever else you'd like to share. Discussions are intended to start conversations, make announcements, celebrate wins, share learnings, and be a starting point for feature ideas and designs.
Issues are our atomic unit of work and are the primary means by which work is planned, tracked, coordinated, and communicated. Issues give work a URL.
Project boards are the means by which work (in the form of issues) is organized, managed, prioritized, and made visible to teams and to the organization.
Markdown files are the primary means by which long-lived information is memorialized. Markdown files live in repositories and are created and modified via pull requests.
Pull requests (PRs) are the primary means by which proposals are reviewed and decisions are finalized. Beyond code changes, pull requests are often made to documentation in the form of Markdown files.
Google Docs are best for ideation, collaborative drafting, early feedback on ideas, and analysis (e.g., spreadsheets). It's not uncommon for ideas to be fleshed out in a Google Doc before being moved to GitHub as a pull request, issue, or discussion, where the content is more easily accessible for a broader audience. Google Docs are rarely best-suited as canonical artifacts due to lack of discoverability and state tracking, so the content should be copied over to GitHub when considered final.
Live meetings (video or IRL) can be helpful for brainstorming, working through complex problems, one-on-one discussions, interpersonal issues, feedback, or just hanging out and getting to know one another. Human conversations deserve the warmth of human faces.
Video recordings are better than live meetings for one-way communication (e.g., for readouts, demos, design iteration, or announcements that do not require any interaction or audience participation). Large meetings should be recorded and shared along with a transcript to make it easier to find specific information.
Email is typically reserved only for things like receiving GitHub.com notifications and external communication. Use email sparingly and only when issues or chat, exposed to the company, would be inappropriate for the conversation.