{"id":1069,"date":"2024-07-23T14:29:06","date_gmt":"2024-07-23T14:29:06","guid":{"rendered":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2024\/07\/23\/how-to-communicate-like-a-github-engineer-our-principles-practices-and-tools\/"},"modified":"2024-07-23T14:29:06","modified_gmt":"2024-07-23T14:29:06","slug":"how-to-communicate-like-a-github-engineer-our-principles-practices-and-tools","status":"publish","type":"post","link":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2024\/07\/23\/how-to-communicate-like-a-github-engineer-our-principles-practices-and-tools\/","title":{"rendered":"How to communicate like a GitHub engineer: our principles, practices, and tools"},"content":{"rendered":"

As a company that\u2019s been remote-first since day one, GitHub Engineering has learned a lot about how to communicate effectively across time zones, teams, and tools. We\u2019ve distilled our experience into a set of guidelines that we call \u201cHow we communicate,\u201d and we\u2019re sharing them with you today<\/a>. We hope that by sharing our communication practices publicly, we can help other organizations that are embracing remote work or want to improve their collaboration culture.<\/p>\n

Read on to learn more about how we use GitHub to build GitHub, how we turned our guiding communications principles into prescriptive practices to manage our internal communications signal-to-noise ratio, and how you can contribute to the ongoing conversation.<\/p>\n

Using GitHub to build GitHub<\/a><\/h2>\n

Unlike many companies that made the transition to remote work during the pandemic, GitHub has been majority remote since its founding 15 years ago. GitHub\u2019s remote-first communication style originally drew inspiration from the open source community. Open source development rarely requires the global community of collaborators and contributors to be in a certain place, at a certain time, in order to participate in the ongoing conversation. This is the same approach GitHub Engineering takes to our own internal communication. We believe that asynchronous communication is the best way to work globally and at scale, and as a result, we\u2019ve built our culture around it.<\/p>\n

We\u2019ve always<\/a> used GitHub to build GitHub. GitHub is not only the place where we host and review code, but also where we plan, discuss, and document our work. We use issues, pull requests, projects, and discussions to track work, collaborate on features, and share information across teams. Many of these communications patterns grew organically, as developers adopted practices from the open source community for our own internal collaboration needs. We believe open practices are the best way to work with a global and diverse team, and to make decisions that are informed, inclusive, and scalable.<\/p>\n

While asynchronous collaboration is deeply embedded in GitHub\u2019s DNA, we have also long had a culture of each team enjoying a great deal of autonomy in deciding how they communicate day to day. This freedom has allowed teams to experiment and uncover novel practices, but it has also meant that working across teams previously required first negotiating a meta-conversation around how to communicate before any substantive work could occur\u2013much like a new open source project negotiating with its newfound community. Having an open set of shared expectations within the engineering organization allows us to be more effective, mindful, and inclusive about how and where we communicate, leading us to make more well-informed decisions in a way that takes into account different needs, preferences, and time zones.<\/p>\n

\u201cHow we communicate\u201d<\/a><\/h2>\n

To define this set of shared expectations, the GitHub Engineering Operations and Culture team collaborated with more than 100 people across the engineering organization in the first half of 2023 to create guidance on \u201cHow we communicate.\u201d This document was intended to encourage consistency over preference by outlining a common core of shared internal communication practices for all of GitHub Engineering in the form of opinionated guidance. Teams are still encouraged to adapt the practices for their unique circumstances, while maintaining a common \u201cAPI\u201d to interface with other teams.<\/p>\n

Today, we are publishing our \u201cHow we communicate\u201d guidance<\/a> under a CC-BY-4.0 license<\/a>, in the hopes that you\u2019ll find it useful, especially if you\u2019re evolving your own remote-first or remote-friendly culture; we welcome you to fork, modify, and use the documentation with attribution. We expect our guidance (lightly edited for the community, primarily to remove internal URLs and references) will evolve over time along with our organization, and, of course, pull requests are always welcome.<\/p>\n

From guiding principles to prescriptive practices<\/a><\/h2>\n

To begin with our \u201cHow we communicate\u201d guidance, we established eight guiding principles:<\/p>\n

Be asynchronous first.
\nWrite things down.
\nMake work visible and overcommunicate.
\nPrefer GitHub tools and workflows.
\nEmbrace collaboration.
\nFoster a culture that values documentation maintenance.
\nCommunicate openly, honestly, and authentically.
\nRemember, practicality beats purity.<\/p>\n

From there, we began to define the specific practices that would help us live up to these principles. We started with the most common forms of communication, such as chat, discussions, issues, project boards, and pull requests, and went on to collaboratively author suggestions on how to manage notifications, run effective meetings, and schedule more inclusively.<\/p>\n

Managing the signal-to-noise ratio<\/a><\/h2>\n

With well over 1,500 engineers across a number of functions, we faced a challenge not unique to any organization: how to keep everyone informed and engaged without overwhelming them with notifications. We wanted to create a system that allowed everyone to opt-in, rather than opt-out, and to get the information they needed in a digestible and skimmable way. As it was, either you got everything (which we jokingly referred to as the \u201cfire hose\u201d of notifications), or you opted out entirely (and ignored everything). Either way, Hubbers were likely to miss important information. We set out to create a system that minimized notification fatigue, while allowing people to subscribe to the topics they cared about.<\/p>\n

We rely on GitHub Discussions heavily to share information within and across teams. It\u2019s a natural choice, since engineers are already working on GitHub.com, and with things like comments, upvotes, and emoji reactions, discussions are a great way to start an asynchronous conversation on just about any topic.<\/p>\n

Opt-in<\/a><\/h3>\n

To start, we encouraged teams to begin posting their discussions to the most logical repository, instead of directly to the main github\/engineering repository. (For example, if a post was about GitHub Copilot, it should go in the github\/copilot repository; if it was about GitHub Actions, it should go in the github\/actions repository.) That way, those interested could subscribe to the repositories they cared about, and get email or web notifications when new discussions were posted. And the volume of notifications coming through github\/engineering to the whole organization would be reduced.<\/p>\n

Amplify widely<\/a><\/h3>\n

But some posts are rightfully intended for all of GitHub Engineering. Things like staff ships (early access to new features for staff), required actions, promotions, and updates to Engineering priorities are written with a broad audience in mind. To ensure we were still surfacing the most important information to the organization, we established a small set of \u201cmagic labels\u201d that if applied to a post, would add it to a daily content roundup, automatically amplify the message in various places for all of GitHub Engineering to see.<\/p>\n

For a peek at our taxonomy, here\u2019s an excerpt from our GitHub Actions workflow that makes it easy for everyone to add the set of \u201cmagic labels\u201d to their repositories:<\/p>\n

label:
\n – name: eng-action-required
\n description: Upcoming process\/workflow changes\/activities requiring Engineering Hubbers to take action
\n – name: eng-availability
\n description: Discussions about availability, incident response, et al
\n – name: eng-celebrations
\n description: Celebrating Hubber promotions and other amazingness
\n – name: eng-feedback-request
\n description: Posts requesting feedback from the Engineering organization
\n – name: eng-org-change
\n description: Announcements related to organizational changes
\n – name: eng-priorities
\n description: Discussions related to Engineering priorities
\n – name: eng-roundup
\n description: Newsletters, weekly digests, and other content and team roundups
\n – name: eng-show-and-tell
\n description: Share what you’ve learned or show off something you’ve made
\n – name: eng-staff-ship
\n description: Announcements for features made available to Hubbers for feedback and early access
\n – name: eng-strategy
\n description: Discussions related to strategy and vision<\/p>\n

Automate all the things!<\/a><\/h3>\n

We used GitHub Actions to schedule a workflow to automatically create daily and weekly roundups of activity across the organization based on those \u201cmagic labels,\u201d posting the digests as discussion posts in the github\/engineering repository.<\/p>\n\n

Like any other discussion post, these content roundups trigger web and email notifications from GitHub.com, and they\u2019re also amplified in Slack channels. However, rather than receiving multiple notifications a day, these roundups reduce the daily notification to one (and also make it much easier to catch up on everything that happens while you\u2019re out of the office!). To support the needs of those who prefer receiving notifications for every discussion post individually, rather than waiting for a daily roundup (aka to instead \u201cdrink from the fire hose\u201d), we created an #engineering-discussions-firehose Slack channel, which streams every labeled post as it is posted.<\/p>\n

Experiment with AI<\/a><\/h3>\n

With notifications reduced in our main github\/engineering repository and discussions being posted in more logical repositories, enabling people to subscribe to more frequent notifications for specific topics, the last remaining step was to increase quick skimmability to allow for greater situational awareness without anyone having to spend all day reading teams\u2019 discussion posts.<\/p>\n

As part of our writing style, most of us include TL;DRs at the top of posts (internet slang for \u201ctoo long, didn\u2019t read,\u201d a short summary of longer writing), but not every post author includes one. For posts that don\u2019t have a human-authored TL;DR, we use Azure\u2019s OpenAI service to draft a brief summary for us. That way, readers can quickly skim the daily digest (or fire hose) and decide if they want to click through to read more.<\/p>\n

Here\u2019s an excerpt of the prompt we use to summarize discussion posts:<\/p>\n

\/\/ OpenAI
\nexport const encodingModel = “gpt-3.5-turbo”;
\nexport const openaiModel = “gpt-35-turbo”;
\nexport const openaiPrompt = `
\n The following is an internal discussion post from the engineering department at GitHub formatted in GitHub flavored Markdown. Please write a short summary appropriate for inclusion in a digest of internal discussion posts with the following requirements:<\/p>\n

– The summary should be no more than 3 sentences
\n – The summary should focus on the most important and impactful information from the post, including key points and any calls to action
\n – The summary should be detailed, thorough, to-the-point, and written for a technical audience, while maintaining clarity and conciseness
\n – The communications style should be professional, but informal
\n – The summary should use emoji where appropriate, but use emoji sparingly
\n – The summary should be formatted in GitHub Flavored Markdown with no line breaks
\n – DO NOT use the phrases “the engineering department” or “at GitHub”; instead, whenever possible, name the specific team in reference, or else use “we” to refer to the team or engineering department. For example, use, “We recently shipped a feature”, and NOT, “The engineering department at GitHub recently shipped a feature”.
\n – Employees at GitHub are referred to as “Hubbers”
\n – GitHub is ALWAYS capitalized as “GitHub”, never “Github”
\n – Teams are referred to as “the Actions team” or “the Copilot team”, never just “actions team” or “copilot team”
\n`;<\/p>\n

export const estimatedPromptTokens = 300;
\nexport const completionTokens = 300;<\/p>\n

Ironically, we relied heavily on GitHub Copilot to build the GitHub Actions workflow (it\u2019s been a while since these Hubbers have written \u201cproduction-worthy\u201d code), meaning robots helped humans to teach robots how to summarize the work of humans, which other robots then published out to other humans. Summarization is a core workflow for AI, and so far, while it\u2019s not always perfect, it\u2019s been working well. If you\u2019re interested in the prompt we\u2019re using (or want to help us improve it!), you can find it here<\/a>.<\/p>\n

Let\u2019s build from here<\/a><\/h2>\n

We\u2019re excited to share our \u201cHow we communicate\u201d guidance with you, and we hope that it will inspire you to adopt or improve some of the practices we\u2019ve found useful. Here are some suggestions to get you started:<\/p>\n

Principles<\/strong>: Establish a set of guiding principles for your organization\u2019s internal communications (fork and clone our guidelines<\/a> for a head start!). What core values do you want to promote, and how can you ensure everyone is aligned around those values so there\u2019s a common \u201cAPI\u201d across teams?
\nPractices<\/strong>: Use those principles to develop practices. What specific practices can you adopt to help you live up to your principles, and how can you ensure those practices are adopted across the organization?
\nExperimentations<\/strong>: Experiment with automation and emerging technologies to improve your practices. How can you use AI and other tools (like GitHub Actions) to automate your workflows and improve the signal-to-noise ratio?<\/p>\n

We recognize communication is an ongoing and evolving process, and different teams and cultures may have different needs and preferences. We welcome your feedback, suggestions, and contributions to our public repository: https:\/\/github.com\/github\/how-engineering-communicates<\/a><\/p>\n

Happy communicating! <\/p>\n

The post How to communicate like a GitHub engineer: our principles, practices, and tools<\/a> appeared first on The GitHub Blog<\/a>.<\/p>","protected":false},"excerpt":{"rendered":"

As a company that\u2019s been remote-first since day one, GitHub Engineering has learned a lot about how to communicate effectively […]<\/p>\n","protected":false},"author":0,"featured_media":0,"comment_status":"","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"site-sidebar-layout":"default","site-content-layout":"","ast-site-content-layout":"default","site-content-style":"default","site-sidebar-style":"default","ast-global-header-display":"","ast-banner-title-visibility":"","ast-main-header-display":"","ast-hfb-above-header-display":"","ast-hfb-below-header-display":"","ast-hfb-mobile-header-display":"","site-post-title":"","ast-breadcrumbs-content":"","ast-featured-img":"","footer-sml-layout":"","ast-disable-related-posts":"","theme-transparent-header-meta":"","adv-header-id-meta":"","stick-header-meta":"","header-above-stick-meta":"","header-main-stick-meta":"","header-below-stick-meta":"","astra-migrate-meta-layouts":"default","ast-page-background-enabled":"default","ast-page-background-meta":{"desktop":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"ast-content-background-meta":{"desktop":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"footnotes":""},"categories":[8],"tags":[],"class_list":["post-1069","post","type-post","status-publish","format-standard","hentry","category-github-engineering"],"_links":{"self":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts\/1069","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/comments?post=1069"}],"version-history":[{"count":0,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts\/1069\/revisions"}],"wp:attachment":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/media?parent=1069"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/categories?post=1069"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/tags?post=1069"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}