├── .github ├── CODEOWNERS ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md └── SUPPORT.md ├── LICENSE.txt ├── README.md ├── how-github-engineering-communicates.md ├── prompt.md ├── quick-ref.md └── tips-for-leaders.md /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @github/technical-business-operations 2 | -------------------------------------------------------------------------------- /.github/CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to making participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, gender identity and expression, level of experience, 9 | nationality, personal appearance, race, religion, or sexual identity and 10 | orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting the project team at opensource@github.com. All 59 | complaints will be reviewed and investigated and will result in a response that 60 | is deemed necessary and appropriate to the circumstances. The project team is 61 | obligated to maintain confidentiality with regard to the reporter of an incident. 62 | Further details of specific enforcement policies may be posted separately. 63 | 64 | Project maintainers who do not follow or enforce the Code of Conduct in good 65 | faith may face temporary or permanent repercussions as determined by other 66 | members of the project's leadership. 67 | 68 | ## Attribution 69 | 70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 71 | available at [http://contributor-covenant.org/version/1/4][version] 72 | 73 | [homepage]: http://contributor-covenant.org 74 | [version]: http://contributor-covenant.org/version/1/4/ 75 | -------------------------------------------------------------------------------- /.github/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | ## Contributing 2 | 3 | Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great. 4 | 5 | Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](./LICENSE.txt). 6 | 7 | Maintenance is provided on a best-level support basis, so please be patient with pull requests! 8 | 9 | Note that this project is released with a [Contributor Code of Conduct](./CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. 10 | 11 | ## Submitting a pull request 12 | 13 | 1. [Fork](https://github.com/github/how-engineering-communicates/fork) and clone the repository 14 | 2. Create a descriptively named branch: `git checkout -b my-branch-name` 15 | 3. Make your change 16 | 4. Push to your fork and [submit a pull request](https://github.com/github/how-engineering-communicates/compare) describing your change 17 | 5. Pat your self on the back and wait for your pull request to be reviewed and merged 18 | 19 | Here are a few things you can do that will increase the likelihood of your pull request being accepted: 20 | 21 | - Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests. 22 | - Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). 23 | 24 | ## Resources 25 | 26 | - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) 27 | - [Using Pull Requests](https://help.github.com/articles/about-pull-requests/) 28 | - [GitHub Help](https://help.github.com) 29 | -------------------------------------------------------------------------------- /.github/SUPPORT.md: -------------------------------------------------------------------------------- 1 | # Support 2 | 3 | ## How to file issues and get help 4 | 5 | This project uses GitHub issues to track bugs and feature requests. Please search the existing issues before filing new issues to avoid duplicates. For new issues, file your bug or feature request as a new issue. For help or questions about using this project, please open an issue or start a discussion. 6 | 7 | How GitHub Engineering Communicates is **not** actively developed but is maintained by GitHub staff **AND THE COMMUNITY**. We will do our best to respond to support and community questions in a timely manner. 8 | 9 | ## GitHub Support Policy 10 | 11 | Support for this project is limited to the resources listed above. 12 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | Attribution 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution 4.0 International Public License 58 | 59 | By exercising the Licensed Rights (defined below), You accept and agree 60 | to be bound by the terms and conditions of this Creative Commons 61 | Attribution 4.0 International Public License ("Public License"). To the 62 | extent this Public License may be interpreted as a contract, You are 63 | granted the Licensed Rights in consideration of Your acceptance of 64 | these terms and conditions, and the Licensor grants You such rights in 65 | consideration of benefits the Licensor receives from making the 66 | Licensed Material available under these terms and conditions. 67 | 68 | 69 | Section 1 -- Definitions. 70 | 71 | a. Adapted Material means material subject to Copyright and Similar 72 | Rights that is derived from or based upon the Licensed Material 73 | and in which the Licensed Material is translated, altered, 74 | arranged, transformed, or otherwise modified in a manner requiring 75 | permission under the Copyright and Similar Rights held by the 76 | Licensor. For purposes of this Public License, where the Licensed 77 | Material is a musical work, performance, or sound recording, 78 | Adapted Material is always produced where the Licensed Material is 79 | synched in timed relation with a moving image. 80 | 81 | b. Adapter's License means the license You apply to Your Copyright 82 | and Similar Rights in Your contributions to Adapted Material in 83 | accordance with the terms and conditions of this Public License. 84 | 85 | c. Copyright and Similar Rights means copyright and/or similar rights 86 | closely related to copyright including, without limitation, 87 | performance, broadcast, sound recording, and Sui Generis Database 88 | Rights, without regard to how the rights are labeled or 89 | categorized. For purposes of this Public License, the rights 90 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 91 | Rights. 92 | 93 | d. Effective Technological Measures means those measures that, in the 94 | absence of proper authority, may not be circumvented under laws 95 | fulfilling obligations under Article 11 of the WIPO Copyright 96 | Treaty adopted on December 20, 1996, and/or similar international 97 | agreements. 98 | 99 | e. Exceptions and Limitations means fair use, fair dealing, and/or 100 | any other exception or limitation to Copyright and Similar Rights 101 | that applies to Your use of the Licensed Material. 102 | 103 | f. Licensed Material means the artistic or literary work, database, 104 | or other material to which the Licensor applied this Public 105 | License. 106 | 107 | g. Licensed Rights means the rights granted to You subject to the 108 | terms and conditions of this Public License, which are limited to 109 | all Copyright and Similar Rights that apply to Your use of the 110 | Licensed Material and that the Licensor has authority to license. 111 | 112 | h. Licensor means the individual(s) or entity(ies) granting rights 113 | under this Public License. 114 | 115 | i. Share means to provide material to the public by any means or 116 | process that requires permission under the Licensed Rights, such 117 | as reproduction, public display, public performance, distribution, 118 | dissemination, communication, or importation, and to make material 119 | available to the public including in ways that members of the 120 | public may access the material from a place and at a time 121 | individually chosen by them. 122 | 123 | j. Sui Generis Database Rights means rights other than copyright 124 | resulting from Directive 96/9/EC of the European Parliament and of 125 | the Council of 11 March 1996 on the legal protection of databases, 126 | as amended and/or succeeded, as well as other essentially 127 | equivalent rights anywhere in the world. 128 | 129 | k. You means the individual or entity exercising the Licensed Rights 130 | under this Public License. Your has a corresponding meaning. 131 | 132 | 133 | Section 2 -- Scope. 134 | 135 | a. License grant. 136 | 137 | 1. Subject to the terms and conditions of this Public License, 138 | the Licensor hereby grants You a worldwide, royalty-free, 139 | non-sublicensable, non-exclusive, irrevocable license to 140 | exercise the Licensed Rights in the Licensed Material to: 141 | 142 | a. reproduce and Share the Licensed Material, in whole or 143 | in part; and 144 | 145 | b. produce, reproduce, and Share Adapted Material. 146 | 147 | 2. Exceptions and Limitations. For the avoidance of doubt, where 148 | Exceptions and Limitations apply to Your use, this Public 149 | License does not apply, and You do not need to comply with 150 | its terms and conditions. 151 | 152 | 3. Term. The term of this Public License is specified in Section 153 | 6(a). 154 | 155 | 4. Media and formats; technical modifications allowed. The 156 | Licensor authorizes You to exercise the Licensed Rights in 157 | all media and formats whether now known or hereafter created, 158 | and to make technical modifications necessary to do so. The 159 | Licensor waives and/or agrees not to assert any right or 160 | authority to forbid You from making technical modifications 161 | necessary to exercise the Licensed Rights, including 162 | technical modifications necessary to circumvent Effective 163 | Technological Measures. For purposes of this Public License, 164 | simply making modifications authorized by this Section 2(a) 165 | (4) never produces Adapted Material. 166 | 167 | 5. Downstream recipients. 168 | 169 | a. Offer from the Licensor -- Licensed Material. Every 170 | recipient of the Licensed Material automatically 171 | receives an offer from the Licensor to exercise the 172 | Licensed Rights under the terms and conditions of this 173 | Public License. 174 | 175 | b. No downstream restrictions. You may not offer or impose 176 | any additional or different terms or conditions on, or 177 | apply any Effective Technological Measures to, the 178 | Licensed Material if doing so restricts exercise of the 179 | Licensed Rights by any recipient of the Licensed 180 | Material. 181 | 182 | 6. No endorsement. Nothing in this Public License constitutes or 183 | may be construed as permission to assert or imply that You 184 | are, or that Your use of the Licensed Material is, connected 185 | with, or sponsored, endorsed, or granted official status by, 186 | the Licensor or others designated to receive attribution as 187 | provided in Section 3(a)(1)(A)(i). 188 | 189 | b. Other rights. 190 | 191 | 1. Moral rights, such as the right of integrity, are not 192 | licensed under this Public License, nor are publicity, 193 | privacy, and/or other similar personality rights; however, to 194 | the extent possible, the Licensor waives and/or agrees not to 195 | assert any such rights held by the Licensor to the limited 196 | extent necessary to allow You to exercise the Licensed 197 | Rights, but not otherwise. 198 | 199 | 2. Patent and trademark rights are not licensed under this 200 | Public License. 201 | 202 | 3. To the extent possible, the Licensor waives any right to 203 | collect royalties from You for the exercise of the Licensed 204 | Rights, whether directly or through a collecting society 205 | under any voluntary or waivable statutory or compulsory 206 | licensing scheme. In all other cases the Licensor expressly 207 | reserves any right to collect such royalties. 208 | 209 | 210 | Section 3 -- License Conditions. 211 | 212 | Your exercise of the Licensed Rights is expressly made subject to the 213 | following conditions. 214 | 215 | a. Attribution. 216 | 217 | 1. If You Share the Licensed Material (including in modified 218 | form), You must: 219 | 220 | a. retain the following if it is supplied by the Licensor 221 | with the Licensed Material: 222 | 223 | i. identification of the creator(s) of the Licensed 224 | Material and any others designated to receive 225 | attribution, in any reasonable manner requested by 226 | the Licensor (including by pseudonym if 227 | designated); 228 | 229 | ii. a copyright notice; 230 | 231 | iii. a notice that refers to this Public License; 232 | 233 | iv. a notice that refers to the disclaimer of 234 | warranties; 235 | 236 | v. a URI or hyperlink to the Licensed Material to the 237 | extent reasonably practicable; 238 | 239 | b. indicate if You modified the Licensed Material and 240 | retain an indication of any previous modifications; and 241 | 242 | c. indicate the Licensed Material is licensed under this 243 | Public License, and include the text of, or the URI or 244 | hyperlink to, this Public License. 245 | 246 | 2. You may satisfy the conditions in Section 3(a)(1) in any 247 | reasonable manner based on the medium, means, and context in 248 | which You Share the Licensed Material. For example, it may be 249 | reasonable to satisfy the conditions by providing a URI or 250 | hyperlink to a resource that includes the required 251 | information. 252 | 253 | 3. If requested by the Licensor, You must remove any of the 254 | information required by Section 3(a)(1)(A) to the extent 255 | reasonably practicable. 256 | 257 | 4. If You Share Adapted Material You produce, the Adapter's 258 | License You apply must not prevent recipients of the Adapted 259 | Material from complying with this Public License. 260 | 261 | 262 | Section 4 -- Sui Generis Database Rights. 263 | 264 | Where the Licensed Rights include Sui Generis Database Rights that 265 | apply to Your use of the Licensed Material: 266 | 267 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 268 | to extract, reuse, reproduce, and Share all or a substantial 269 | portion of the contents of the database; 270 | 271 | b. if You include all or a substantial portion of the database 272 | contents in a database in which You have Sui Generis Database 273 | Rights, then the database in which You have Sui Generis Database 274 | Rights (but not its individual contents) is Adapted Material; and 275 | 276 | c. You must comply with the conditions in Section 3(a) if You Share 277 | all or a substantial portion of the contents of the database. 278 | 279 | For the avoidance of doubt, this Section 4 supplements and does not 280 | replace Your obligations under this Public License where the Licensed 281 | Rights include other Copyright and Similar Rights. 282 | 283 | 284 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 285 | 286 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 287 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 288 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 289 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 290 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 291 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 292 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 293 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 294 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 295 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 296 | 297 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 298 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 299 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 300 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 301 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 302 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 303 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 304 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 305 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 306 | 307 | c. The disclaimer of warranties and limitation of liability provided 308 | above shall be interpreted in a manner that, to the extent 309 | possible, most closely approximates an absolute disclaimer and 310 | waiver of all liability. 311 | 312 | 313 | Section 6 -- Term and Termination. 314 | 315 | a. This Public License applies for the term of the Copyright and 316 | Similar Rights licensed here. However, if You fail to comply with 317 | this Public License, then Your rights under this Public License 318 | terminate automatically. 319 | 320 | b. Where Your right to use the Licensed Material has terminated under 321 | Section 6(a), it reinstates: 322 | 323 | 1. automatically as of the date the violation is cured, provided 324 | it is cured within 30 days of Your discovery of the 325 | violation; or 326 | 327 | 2. upon express reinstatement by the Licensor. 328 | 329 | For the avoidance of doubt, this Section 6(b) does not affect any 330 | right the Licensor may have to seek remedies for Your violations 331 | of this Public License. 332 | 333 | c. For the avoidance of doubt, the Licensor may also offer the 334 | Licensed Material under separate terms or conditions or stop 335 | distributing the Licensed Material at any time; however, doing so 336 | will not terminate this Public License. 337 | 338 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 339 | License. 340 | 341 | 342 | Section 7 -- Other Terms and Conditions. 343 | 344 | a. The Licensor shall not be bound by any additional or different 345 | terms or conditions communicated by You unless expressly agreed. 346 | 347 | b. Any arrangements, understandings, or agreements regarding the 348 | Licensed Material not stated herein are separate from and 349 | independent of the terms and conditions of this Public License. 350 | 351 | 352 | Section 8 -- Interpretation. 353 | 354 | a. For the avoidance of doubt, this Public License does not, and 355 | shall not be interpreted to, reduce, limit, restrict, or impose 356 | conditions on any use of the Licensed Material that could lawfully 357 | be made without permission under this Public License. 358 | 359 | b. To the extent possible, if any provision of this Public License is 360 | deemed unenforceable, it shall be automatically reformed to the 361 | minimum extent necessary to make it enforceable. If the provision 362 | cannot be reformed, it shall be severed from this Public License 363 | without affecting the enforceability of the remaining terms and 364 | conditions. 365 | 366 | c. No term or condition of this Public License will be waived and no 367 | failure to comply consented to unless expressly agreed to by the 368 | Licensor. 369 | 370 | d. Nothing in this Public License constitutes or may be interpreted 371 | as a limitation upon, or waiver of, any privileges and immunities 372 | that apply to the Licensor or You, including from the legal 373 | processes of any jurisdiction or authority. 374 | 375 | 376 | ======================================================================= 377 | 378 | Creative Commons is not a party to its public 379 | licenses. Notwithstanding, Creative Commons may elect to apply one of 380 | its public licenses to material it publishes and in those instances 381 | will be considered the “Licensor.” The text of the Creative Commons 382 | public licenses is dedicated to the public domain under the CC0 Public 383 | Domain Dedication. Except for the limited purpose of indicating that 384 | material is shared under a Creative Commons public license or as 385 | otherwise permitted by the Creative Commons policies published at 386 | creativecommons.org/policies, Creative Commons does not authorize the 387 | use of the trademark "Creative Commons" or any other trademark or logo 388 | of Creative Commons without its prior written consent including, 389 | without limitation, in connection with any unauthorized modifications 390 | to any of its public licenses or any other arrangements, 391 | understandings, or agreements concerning use of licensed material. For 392 | the avoidance of doubt, this paragraph does not form part of the 393 | public licenses. 394 | 395 | Creative Commons may be contacted at creativecommons.org. 396 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # How to communicate like a GitHub engineer: Our principles, practices, and tools 2 | 3 | As a company that's been remote-first since day one, GitHub Engineering has learned a lot about how to communicate effectively across time zones, teams, and tools. We've distilled our experience into a set of guidelines that we call "How we communicate". 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. 4 | 5 | For 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, check out [this blog post](https://github.blog/2023-10-04-how-to-communicate-like-a-github-engineer-our-principles-practices-and-tools/). 6 | 7 | [Pull requests are welcome](.github/CONTRIBUTING.md)! 8 | 9 | ## Contents 10 | 11 | * [How GitHub Engineering communicates](how-github-engineering-communicates.md) 12 | * [Quick reference](quick-ref.md) 13 | * [Tips for leaders](tips-for-leaders.md) 14 | * [Example Azure OpenAI prompt](prompt.md) 15 | 16 | ## License 17 | 18 | This documentation is released under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). 19 | -------------------------------------------------------------------------------- /how-github-engineering-communicates.md: -------------------------------------------------------------------------------- 1 | # How GitHub Engineering communicates 2 | _(Community version, lightly edited, primarily to remove internal URLs and references)_ 3 | 4 | For a tl;dr version of this document, see [the companion quick-reference guide](./quick-ref.md). 5 | 6 | # Purpose and motivation 7 | 8 | GitHub has long had a culture of each team enjoying a great deal of autonomy in deciding how they communicate day-to-day. While this freedom allows teams to experiment and uncover novel practices, it also means that working across teams requires first negotiating a meta-conversation around how to communicate before any substantive work can occur. Having an open set of shared expectations within the Engineering organization will allow 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. 9 | 10 | This document is intended to encourage consistency over preference by outlining a common core of shared internal communication practices for all of Engineering in the form of opinionated guidance, and it was informed by a survey run within the Engineering organization in March 2023. Teams are still encouraged to adapt the practices for their unique circumstances, maintaining a common "API" to interface with other teams. 11 | 12 | We expect this document and the guidance within will evolve over time along with our organization, and pull requests are welcome. 13 | 14 | # Guiding principles 15 | 16 | Overall, the way we communicate as an Engineering organization is informed by the following principles: 17 | 18 | ## Be asynchronous first 19 | 20 | Asynchronous communication is any kind of communication where there is a delay between the information being provided by the sender and the time when the recipient accepts the information and acts on it. 21 | 22 | Working asynchronously has [a number of benefits](https://ben.balter.com/2022/03/17/why-async/#benefits-of-working-asynchronously). Knowledge workers [are most productive](https://en.wikipedia.org/wiki/Flow_(psychology)) when they have large blocks of uninterrupted time. A two-hour block of time is not fungible with four 30-minute blocks. Unlike working on an assembly line, for example, when knowledge work is accidentally or intentionally interrupted – whether by a popup, a meeting, or a "hey, you got a sec?" drive-by – there's a significant context-switching cost to get back to where you were. Whenever possible, prefer issues and chat messages to "just in time" communications (like a last-minute meeting), reserving more synchronous methods as points of escalation only when the urgency or complexity of the communication requires it (e.g., for tasks that are time-sensitive and business-critical). 23 | 24 | And there's an added bonus: Asynchronous mediums necessitate a distributed workflow. There's no "you had to be there" when "there" is online and anytime. 25 | 26 | ## Write things down 27 | 28 | If we want to be asynchronous first as a globally distributed organization, it's essential that we write things down – especially the "why" and the "how" of decisions – in the most durable, searchable, and discoverable medium possible. We prefer workflows that don't require anyone to be in a certain place at a certain time working on a certain thing in order to collaborate with one another, and one practical way to do this is to ensure every task, idea, or decision has its own URL (meaning if someone asks a question, you can provide them a link to the answer). 29 | 30 | There are [a number of advantages](https://ben.balter.com/2015/11/12/why-urls/#the-value-of-giving-concepts-urls) to capturing and exposing processes through URLs. Beyond supporting our asynchronous and distributed workflows, writing things down serves as a message in a bottle to our future selves and our future peers, recording what decisions were made and why, capturing and exposing process and decision making. 31 | 32 | ## Make work visible and overcommunicate 33 | 34 | Capturing and exposing processes through URLs also helps make your work more visible. So [work in the open](https://ben.balter.com/2022/02/16/leaders-show-their-work/) and proactively share your work to the widest extent practical. As we continue to grow as an organization, points of collaboration will become even more important as we try to reduce redundant work. Avoid hoarding information: Like in any production system, observability is key. And if you make something useful, find a way to make it available so others can benefit from it too. 35 | 36 | Let others opt-in to context and subscribe to updates. Make it easy for others to understand what's going on, and be sure to add a tl;dr summary at the beginning of any communication to ensure your main points get across. 37 | 38 | ## Prefer GitHub tools and workflows 39 | 40 | The best way to work in the open and to make that work visible is to use GitHub tools and workflows, but only use them when they make sense (and don't use them when they don't). The most important thing is to favor systems that naturally capture and expose processes, and if you don't choose to use them initially (e.g., you make decisions via chat or in a live meeting), be sure to durably capture outcomes after the fact. 41 | 42 | ## Embrace collaboration 43 | 44 | Software development is a team sport. Proactively seek input and feedback early and often. Document not just decisions, but also the context, tradeoffs, and consequences, and do so in a way that allows stakeholders to actively participate in the decision-making process. 45 | 46 | Opening a pull request (or posting a discussion or opening an issue) is not collaborative in and of itself. Here are a few tips for more collaborative decision making: 47 | 48 | * Seek feedback _before_ the decision is made (don't make a decision and then ask for feedback on it). Statements should be more in the form of "I intend to" rather than "I decided". 49 | * Documents should be a collaboration between authors (decision-makers) and stakeholders to agree on what the problem is, what constraints exist, and how (and when) the problem is going to be solved. 50 | * Documents should live in a location where they are easy to discover (remember to make work visible!). 51 | * Documents should have sufficient detail, including things like availability, rollout strategy, scaling patterns, and timelines. 52 | * Be generous with links in documents, as they are often part of a larger conversation. It's helpful to link to issues, discussions, or other artifacts that provide more context to a decision. 53 | 54 | ## Foster a culture that values documentation maintenance 55 | 56 | We should place as much importance on documentation maintenance as we do on creating good documentation in the first place. Whenever teams are reorganized, or whenever code or processes change, remember to update any relevant documentation and its ownership metadata. 57 | 58 | This might require managers to build time to update documentation into team work plans, but the time spent updating documentation will be saved the next time someone accesses it (i.e., if someone finds documentation that's outdated or incorrect, confidence in internal tools decreases and a lot of time is wasted trying to track down the correct information). Leave things better than how you found them: If you find outdated documentation, open a pull request or file an issue for the relevant team to correct it. 59 | 60 | However, document maintenance should not be a burden. If a document's maintenance outweighs its benefits, it should be deleted or simplified. 61 | 62 | ## Communicate openly, honestly, and authentically 63 | 64 | We are humans, and we appreciate communication that is transparent and direct so that we don't have to spend time trying to extract meaning from heaps of corporate buzzwords. Say what you mean, in a respectful way, and listen to understand each other (e.g., communication patterns and tone can vary across cultures, so ask for clarification before making any assumptions about intent). And when drafting a more complex communication, like when announcing a process or tooling change, try to anticipate any questions your colleagues might have and provide an accompanying FAQ if needed. Be open about what you know and what you don't – it's better to say "we don't know yet" or "we can't answer this right now" than to pretend the question doesn't exist. 65 | 66 | ### Strive for inclusivity 67 | 68 | Strive for inclusivity, whether choosing date formats, avoiding acronyms without context, or generally being more aware of time zones when scheduling meetings or sending chat messages. Practice inclusive language in all communications. And be mindful of accessibility (e.g., ensure images have alt-text, use semantic Markdown headings and descriptive link texts). 69 | 70 | ### Use emoji and animated GIFs 71 | 72 | Emoji and animated GIFs are the facial expressions and body language of online writing. Use them to convey emotion / tone and celebrate wins. Communication should always remain professional and respectful, but it doesn't have to be formal. 73 | 74 | There's a reason our collaboration culture is built on a foundation of emoji and animated GIFs: It's not simply because animated GIFs of kittens are adorable, but because a :trollface: is often the most efficient way to express sarcasm. Not to mention, emoji can make our communication more inclusive, especially for the neurodiverse and those for whom English is not their first language. 75 | 76 | Do note that while humor and creativity can keep things interesting and help convey tone, not everyone is a fan of animations, so use GIFs and animated emoji (e.g., sirens and alarms) in moderation. If you find animations distracting, [adjust your GitHub settings to prevent autoplay](https://github.blog/changelog/2022-05-19-option-to-prevent-animated-images-from-playing-automatically/). 77 | 78 | Don't fret about using the "wrong" emoji, and if you're struggling to find the right one, GitHub alumna `@muan` created [this handy emoji searcher tool](https://emoji.muan.co/). To support accessibility, ensure custom emoji have a semantically meaningful name (as some people opt to convert emoji to plain text), and if you use an animated GIF on GitHub.com, be sure to include an "alt text" description so that the image is accessible to all (e.g., `![a puppy yawning](puppy-yawning.gif)`). 79 | 80 | Finally, it's a good practice to use emoji reactions on discussions, issues, and in chat as an async and low-noise way to acknowledge that you've read something (or your thoughts on the subject, serious or otherwise). You'll often see others "ACK"-ing a chat message to **ack** nowledge that they've seen it, even if they can't respond at the moment. Don't think it's rude. This is a nod to the SYN-ACK handshake in the TCP networking protocol. (Yes, we are a bunch of nerds.) 81 | 82 | ## Remember practicality beats purity 83 | 84 | Remember that these are guidelines, not rules. Process should drive outcomes. Favor intent over mechanics, and encourage pragmatism. 85 | 86 | # Communication channels 87 | 88 | This section describes which communication channel we prefer for which purpose. 89 | 90 | ## Chat 91 | 92 | After GitHub.com, chat (e.g., Slack) is one of the most common ways we collaborate. Chat is great for real-time coordination, quick questions, and to stay connected throughout the day, but it is ephemeral and provides no guarantee of delivery, especially across time zones (where it can be unintentionally exclusive). Chat is one of our primary communication (and culture) tools, but it shouldn't be your sole means of communication within your team. 93 | 94 | Generally, use chat for informal office communication, for community comradery, for water-cooler talk, for tactical coordination, to amplify messages communicated elsewhere, and for other time-sensitive matters that are best handled semi-synchronously, but not as a primary means of decision making or a canonical source of truth (due to its lack of discoverability and permanence). A general principle is to use chat as a means of escalation if you've been going back and forth on an issue or pull request for days without resolution, and if you still haven't reached consensus after several rounds of responses, take it to a call (and then be sure to durably record the decision once it has been made). 95 | 96 | Treat chat as transient and hold each other accountable for writing important things down more durably. 97 | 98 | ### Tips for making chat most effective 99 | 100 | #### General tips 101 | 102 | * Chat is asynchronous. [Don't force synchronous interactions](https://nohello.net/en/) (e.g., don't just send a "hello"; go ahead and share context/links or ask your question in your initial message). Use `@here` and `@channel` sparingly, if ever, and only for messages that are both urgent AND important. 103 | * Unless a message is marked urgent, aim to respond within one business day during your working hours. Treat direct messages (DMs) more like email or text messages and less like a phone call. 104 | * If you urgently need a response to an issue or pull request, include the URL in your message and ask for a response there. 105 | * Post in public channels (rather than using DMs) whenever possible to encourage knowledge sharing, organic situational awareness, and crowdsourcing of responses. You're more likely to get a better answer, more quickly, and chances are others may share the same question and benefit from hearing the answer. Only use DMs for when the subject requires it, and if it doesn't, encourage moving the conversation to a public channel. 106 | * Don't be afraid to post in public channels for fear of creating "too much noise", but do try to find the most specific channel for the subject. Use threads and emoji reactions liberally to increase the channel's signal-to-noise ratio. 107 | * Don't assume everyone in a channel has read every message. There is no expectation that anyone catch up on channels when returning from PTO. 108 | * Update your profile to include your preferred name, name pronunciation, pronouns, and "what [you] do here" to help others better understand your role. Pro-tip: Include a link to your [Human User Guide (HUG)](https://github.com/matthewmccullough/human-interaction-templates/blob/master/human-user-guide.md). 109 | 110 | #### When chat is great 111 | 112 | * Chat is a good way to get initial feedback in real-time with people who happen to be around. However, any announcements or longer-term decisions should be documented in a discussion, issue, or pull request. That gives everyone an opportunity to review and be aware of the decision and serves as a more durable, permanent record should we need to refer back to it later. 113 | * Chat is also a good way to get solutions to temporary technical issues (e.g., "my codespace is behaving strangely, does anyone know what's going on?"), but if you find the issue is persistent and requires a workaround, document the process in a more durable location. 114 | * ChatOps (commands run via chat that are visible to others) for common tasks are a great way to bring visibility to work and allow others to learn through observation beyond formal onboarding. 115 | 116 | #### Tips for notifications 117 | 118 | * Set your status and turn off notifications (or log out of chat altogether) when you need focus time or are out of office. You can also set a "notification schedule" to automatically silence notifications outside of working hours. Unless you are on call, there is no expectation that you're online or responsive 24/7 (even if the message is from your manager). 119 | * Be thoughtful about pushing notifications through outside of working hours when the recipient has turned them off, and consider [scheduling](https://slack.com/help/articles/1500012915082-Schedule-messages-to-send-later) chat messages to be sent later if your message is outside of the recipient's working hours. 120 | * Be mindful of vertical space when posting links with previews, especially in larger channels. 121 | 122 | #### Tips for creating channels 123 | 124 | * Prefer named channels (e.g., #tmp-topic-working-space) over group DMs as it's easier to add people to the conversation later if needed (and to keep track of the topic of discussion). 125 | * Prefer creating public (to the company) channels, unless there is a compelling reason for the channel to be private. 126 | * Keep channel topics as specific as possible. Prefer small, specific channels over large, generic channels. This allows people to opt in to the information they want. 127 | * Keep noisy bots out of non-bot channels. 128 | * Ensure any channels you create have a clear description describing the purpose of the channel and the intended audience. 129 | * Archive channels once they serve their purpose. 130 | 131 | ## GitHub 132 | 133 | ### Repositories 134 | 135 | A repository (or "repo") is 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. Each repo contains discussions, issues, Markdown files, and pull requests. 136 | 137 | Create repositories for distinct teams and work streams for ease of discoverability and transferability. Be sure to grant the "employees" team "write" permissions to any repository you create to ensure everyone in the company can view it and submit pull requests. If you're worried about "rogue" commits, you can use branch protection and CODEOWNERS to require your team's review. For repos intended for documentation rather than code, consider allowing PRs to be merged without a review; that way, you get the more detailed change tracking of a PR, but avoid much of the friction of the review process. At least one team should have "admin" permissions for the repository. 138 | 139 | Also be sure to include a README.md file that provides basic information about your repo and keep it updated so the information is current. For example, for a team repo, the README would list the team's charter, org chart, communications channels, and breadcrumbs that help orient people as to where the team fits in the organization (e.g., "Company → Organization → Team"). 140 | 141 | And finally, when a project is no longer funded, a team has been restructured, or there is some other reason why the content in a repository is no longer relevant or it is no longer being maintained, close out all remaining issues and pull requests, update the README file and description noting the change, and then [archive the repository](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories). In many cases, cleaning up after the fact is just as helpful to future travelers as capturing the work in progress while it was happening. 142 | 143 | ### Discussions 144 | 145 | Discussions are intended for long-lived conversations that don't involve a todo/shipped state (although you can now "close" a discussion if it is time bound). Discussions are great for Q&A, internal updates, or social discussions, as well as a starting point for feature ideas and designs. You can even treat discussions like an internal blog. 146 | 147 | Discussions enjoy many of the benefits of issues, except they are more suited for ongoing discussions, broadcasts, or blog-like posts with comments that live outside day-to-day work streams. 148 | 149 | ### Issues 150 | 151 | Have a question? Open an issue. Have an idea? Open an issue. Notice something's a bit wonky? You guessed it, open an issue. Issues are cheap. They cost seconds to create, and even if duplicative, are closed just as easily. Issues start conversations, surface alternate points of view, and most importantly, create permanent, searchable, and linkable records of internal conversations, even if the answer ultimately landed on is "wontfix". They naturally capture and expose processes, can easily loop in additional teams, create opt-out-able notifications, cross-link to other issues for ease of discoverability, and can be closed out once the required action is complete to increase the visibility of in-flight efforts. Issues are a placeholder for action the organization needs to take (or needs to decide not to take), and whether they relate to a bug, a feature, or a blog post to be written, they exist to be organized, discussed, and assigned. Don't fret over which repo is "right", as issues can be easily moved between repos within the organization. 152 | 153 | Issues on GitHub.com are the atomic unit of work across teams and the primary means by which work is planned, tracked, managed, coordinated, communicated, and shared. Issues bring the most value to teams when conversations and status updates happen on and around the issue, rather than the issue being used as a "TODO" with only an open and closed state. 154 | 155 | When issues are long-lived or heavily commented, it's a good practice to keep the issue body (sometimes referred to as the "OP" in internet jargon) up to date for anyone first coming to the issue and to regularly summarize the discussion as a comment that restates the current understanding of the problem and its proposed solution. Also note that if there's more ambiguity, questions of "should we even do this", or "we should do this but there are so many ways to implement it that we should consider", a discussion might be a better starting point. Issues can come out of discussions eventually, once decisions have been made. 156 | 157 | #### Keep issues logically distinct 158 | 159 | The great thing about issues and pull requests, in contrast to something like email, is that they [can be split](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue#creating-an-issue-from-a-comment) when topics diverge. This keeps teams focused on :ship:ing one thing and only one thing at a time. Additionally, discrete topics minimize unnecessary noise and optimize for fast decision-making by ensuring only the most relevant teams are involved. 160 | 161 | In practice, that means an issue should have one purpose, defined by the title at the top of the page. When a concern not directly related to the thread's purpose arises through the course of the conversation, as they often do, open a new issue and encourage participants to continue the discussion there, or if you see a teammate hijacking the conversation, do the same on their behalf. If the sub-task is a blocker, note it as such and move on. 162 | 163 | #### Cross-link related issues and pull requests (PRs) 164 | 165 | Cross-link related issues and pull requests for discoverability. Use task lists to enumerate sub-tasks. Do not do a significant amount of work that's not tracked by an issue. If necessary, ask people to open issues, or open them yourself. 166 | 167 | If you reference something – be it a prior issue, the pull request that implemented a feature, a line in a file, whatever  –  and that thing has a URL, it's your obligation to find that URL and make that reference a link. Even if the reader could theoretically search for it, you are infinitely more familiar with the thing you're referencing, and given a comment read by 5, 10, or 50 people, it's more efficient for you to look it up once than for readers to look it up 50 times. Not to mention, on GitHub, linking to another issue or pull request creates a visible cross-reference, meaning that just by commenting, you create an organic map of the organization's knowledge. 168 | 169 | ### Project boards 170 | 171 | The ways different teams track work can vary (e.g., milestones, tracking issues, task lists), but in general, issues track state at the task level and projects track state at the project level - what's on deck, what's in flight, what's done, who's working on what, etc. When using issues (instead of cards) to track work, projects have all the benefits of issues, but offer a perspective one level of abstraction up. 172 | 173 | ### Markdown files 174 | 175 | Pull requests, and thus diffs, are at the core of our workflow. Whether the change is to code, configuration, or prose text, being able to see exactly what's proposed on an extremely granular level, without the need to download special software or leave the browser is key. If your colleague can't see what you're proposing, there's no way for you to have a serious discussion on its merits. 176 | 177 | In practice, that means, as early as the drafting stage, prefer formats like Markdown. Tools like Google Docs are great for collaboration early in an idea's lifecycle, but your goal should be to memorialize the document in an issue, discussion, or pull request for visibility and reach. 178 | 179 | Open formats not only allow for diffing, but also facilitate targeted discussions through line-by-line commenting. When that's not possible (e.g., when making tweaks to a site's design), provide before and after screenshots within the pull request body to minimize the burden on reviewers. Remember, you're asking others to take time out of their day to provide feedback on your proposed change. Optimize for their experience, not yours. 180 | 181 | ### Pull requests (PRs) 182 | 183 | Pull requests are the primary means by which proposals are reviewed and decisions are finalized. Sometimes, merging a pull request can be a signal of a decision having been accepted; other times, it's capturing the current state of things, with the expectation that documentation will evolve as we learn more information. 184 | 185 | Unless it's a minor typo so irrefutable that no one would possibly question it or need to be notified of the change, the only way to change community content is with a pull request. It doesn't matter if it's code, configuration, or internal policy: For 99% of changes, committing directly to main is not the appropriate choice. 186 | 187 | If your pull request closes an issue, link to it by including "closes #123" or "fixes #123" in the body to automatically close the issue once the pull request is merged. If a review isn't automatically requested from an appropriately responsible team, be sure to `@mention` the team to make ownership clear for anyone who comes by in the future (an exception is support requests, where you should seek out the on-call individual and `@mention` them directly). And if you raise a pull request and notice an unrelated team is pinged for CODEOWNER review, it's your responsibility to update the ownership information as part of your requested change. 188 | 189 | To keep things actionable when reviewing a pull request, prefer specific in-line comments (ideally with suggested changes) over sweeping, document-wide reviews. Avoid "changes requested" unless you intend to block the pull request from merging without your explicit approval. It's not just about the change you're making today, but allowing others to understand context down the line. 190 | 191 | ### Managing GitHub notifications 192 | 193 | While we may not often use email internally, we rely heavily on GitHub notifications. Like your email inbox, it is expected that you subscribe to the appropriate repos, regularly check your GitHub notifications, and respond to `@mentions` and team mentions as necessary. To cut down on some of the noise, consider [enabling the "Only notify requested team members"](https://docs.github.com/en/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team#about-team-notifications) code review setting for your teams so you can request specific individuals for review without notifying the entire team. 194 | 195 | Teams and individuals should strive to respond to non-urgent GitHub notifications within one business day during their regular working hours. If an issue or comment fails to garner a response, consider escalating the issue to the appropriate chat channel. 196 | 197 | [Notifications](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications) can be delivered either via email, mobile, or as web notifications via your GitHub.com inbox ([here's one real-world example](https://ben.balter.com/2020/08/25/how-i-manage-github-notifications/) of how to manage notifications). To enable notifications, go to the GitHub Settings page and select [Notifications](https://github.com/settings/notifications). Scroll to the "Participating" section and opt in to email and/or web and mobile notifications. 198 | 199 | Whether in GitHub notifications or notifications via any other communications tool, always provide context when `@mentioning` another person. A contextless "`@monalisa`" notification is a lot less actionable than a specific request or call to action. And if you're only referring to someone, but don't actually need their attention, surround the `@mention` in backticks (`) to avoid the ping. 200 | 201 | ## Google Docs 202 | 203 | Google Docs are great for early ideation with a small, trusted group (and it's easier to change the visibility of a Google Doc for different people than it is to manage permissions in a repo), but Google Docs are not as great as a canonical source of truth due to lack of discoverability and closed-by-default permission model. Once an idea becomes sufficiently mature and is ready to be shared more broadly, memorialize it on GitHub via an issue, discussion, or pull request. 204 | 205 | Google Docs discovery is poor, as is understanding the state of a document once you discover it and gain access. Use a Google Doc early in an idea's lifecycle, but burn it down as soon as possible and replace the content with a link to the canonical source in GitHub to avoid confusion. Google Docs are great for ideation and definition (or in-meeting note taking), with the goal of ultimately memorializing the document in an issue or PR for visibility and reach. Think of it as "top-of-the funnel collaboration". 206 | 207 | Here are some additional tips for using Google Docs: 208 | 209 | * Include the document owner, status, and shareability at the top of the document. 210 | * Once moved to GitHub, include the URL in the Google Doc along with a note about the document's status. 211 | * Default to sharing documents with the organization (ability to comment), unless sensitive. 212 | * For longevity, prefer documents in shared drives over an individual person’s account. 213 | 214 | ## Live meetings 215 | 216 | When we say that GitHub is "async first", we mean that literally. Synchronous meetings shouldn't be required to kick off an initiative; instead, they are a [point of escalation](https://ben.balter.com/2023/04/20/meetings-are-a-point-of-escalation/) based on complexity. 217 | 218 | Of course, the percentage of time you spend in meetings will vary depending on your role. Some roles, like that of manager, require more synchronous connections (e.g., 1:1s with reports, cross-functional leadership team meetings, coaching sessions) than others. We should always strive to use the right tool for the job, and for managers, based on the jobs they have, that might mean more frequent live meetings. 219 | 220 | Here are some ways to ensure meetings are effective: 221 | 222 | * Meetings are an incredibly valuable tool when used correctly. Quickly escalate to meetings when the topic calls for it (e.g., interpersonal conflict/connection, problem solving, when you've been unable to reach a resolution via GitHub or chat). 223 | * Meeting topics should be as specific as possible and have the minimum number of the right attendees who remain present and engaged. You are encouraged to leave a meeting if it is not a valuable use of your time. 224 | * Unless it's an informal/social call, all meetings must have an agenda and clear goals (you are empowered to decline if they do not). Consider an ongoing agenda/notes doc to queue up topics for recurring meetings. Phrase agenda items in the form of questions to make it easier to determine if meeting goals were accomplished. 225 | * Meetings should start and end on time. If you finish early, consider using the remainder of the time for informal conversations and to connect as humans. 226 | * Use meetings to discuss information, not to convey it. Send information ahead of time as a pre-read. Do not make any major announcements in live meetings without sending prior written communications. 227 | * Meetings shouldn't be used for status updates, to force work to happen (e.g., scheduling time with someone to ensure they complete a task), or for any task that's best handled asynchronously. 228 | * Memorialize decisions after the meeting in a durable medium. Ad-hoc meetings do not necessarily constitute a final decision (especially on technical matters). See "Write things down" earlier in this document. 229 | * Unless you're having a personal conversation or are discussing sensitive content, record the meeting so those who couldn't join live can catch up. 230 | 231 | Here are a few additional meeting pro-tips: 232 | 233 | * Either enable "speedy meetings" (end 5/10 minutes early) in your calendar settings or schedule meetings to start 5/10 minutes late to allow for time to be human between meetings, and be strict about ending (or starting) at the specified time. 234 | * In smaller meetings, use the meeting chat for side conversations. Share links outside the meeting via chat (e.g., Slack) so they remain after the meeting concludes. 235 | * In larger meetings (or webinars), consider disabling the meeting chat and opening a separate chat (e.g., Slack) channel for discussion, as screen readers by default read messages posted to the meeting chat over the voice of the presenter. 236 | * Keep your camera on whenever practical. To reduce video-call fatigue, try minimizing the size of the meeting window on your screen and/or turning off your "self view". 237 | * Practice inclusivity: Give people multiple ways to interact, so they can choose the ones that make them most comfortable. Encourage hand raising and use of the meeting chat. 238 | * Managers, be explicit with your team members about which meetings are considered mandatory and which can be skipped (or which meetings they can catch up on via recording at their convenience). Meeting loads can get out of hand, and sometimes it's hard to figure out what's required and what's just FYI. 239 | * Be mindful of holidays and working hours, especially across time zones. You can find someone’s timezone in their chat profile (or in their calendar when you are scheduling a meeting). You can also specify your working hours [on your calendar](https://support.google.com/a/users/answer/9308669?hl=en) to help with scheduling. 240 | * When referring to a meeting time, be sure to include the time zone, and try to avoid location-specific references like "this morning" or "in the Spring" to describe timing. Prefer the ISO 8601 standard YYYY-MM-DD (except in long-form writing), but anything consistent and unambiguous will do. 241 | 242 | ### Calendar invites, settings, and entitlements 243 | 244 | Scheduling is hard, especially across time zones. To make it easier on your colleagues, you can modify [your Google Calendar settings](https://calendar.google.com/calendar/r/settings) to enable the "modify event" default guest permissions. That way, if something comes up, the person you're meeting with can propose an alternate time that works better for them. 245 | 246 | Better still, if your role allows, modify your default calendar's permission by checking the "Make available for the organization" box to allow others to see descriptions of your events. Asking someone if they can reschedule a 1:1 or a task reminder you have blocked off is a lot different than rescheduling a customer meeting or daycare drop off. Of course, if you do that, you'll want to mark any potentially sensitive events as private. 247 | 248 | ## Video recordings 249 | 250 | In the spirit of "be asynchronous first", if you have a unidirectional broadcast (e.g., for readouts, demos, design iteration, or announcements that do not require any interaction or audience participation), consider uploading and sharing a recording rather than scheduling a live meeting. 251 | 252 | Also, unless you're having a personal conversation or are discussing sensitive content, be sure to record all meetings and share the recording so those who couldn't join live can catch up. Transcripts also make it much easier to find specific information. 253 | 254 | For sociability, consider scheduling "watch parties" for recorded content, allowing people the optional opportunity to see each other's faces before playback begins and to use meeting chat to interact during playback. 255 | 256 | ## Email 257 | 258 | Email is an ineffective collaboration medium and an even worse mechanism for storing organizational knowledge. There's no opt-in or opt-out mechanisms, no ability to link to or cross-reference discussions, and conversation history lives in a teammate's personal inbox, so when they leave, so too does the thread's context. Use email sparingly and only when issues or chat, exposed to the company, would be inappropriate for the conversation. Put another way, email is for sensitive conversations (or for conversations with people outside the company). 259 | 260 | In practice, that means email is typically reserved only for things like personnel discussions, one-to-one feedback, and external communication. The same goes for other mediums (like phone calls) that don't automatically capture and surface context. If you can have the conversation in a better medium, you should. 261 | -------------------------------------------------------------------------------- /prompt.md: -------------------------------------------------------------------------------- 1 | 2 | To summarize discussion posts for ease of skimming, we use the following instructions and prompt with the `gpt-35-turbo` model hosted on the [Azure OpenAI service](https://azure.microsoft.com/en-us/products/ai-services/openai-service): 3 | 4 | ## Instructions 5 | 6 | ```markdown 7 | You are a technical communications specialist within the Engineering department at GitHub, and you excel at summarizing internal communications for the internal GitHub Engineering audience. 8 | ``` 9 | 10 | ## Prompt 11 | 12 | ```markdown 13 | 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: 14 | 15 | - The summary should be no more than 3 sentences 16 | - The summary should focus on the most important and impactful information from the post, including key points and any calls to action 17 | - The summary should be detailed, thorough, to-the-point, and written for a technical audience, while maintaining clarity and conciseness 18 | - The communications style should be professional, but informal 19 | - The summary should use emoji where appropriate, but use emoji sparingly 20 | - The summary should be formatted in GitHub Flavored Markdown with no line breaks 21 | - 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". 22 | - Employees at GitHub are referred to as "Hubbers" 23 | - GitHub is ALWAYS capitalized as "GitHub", never "Github" 24 | - Teams are referred to as "the Actions team" or "the Copilot team", never just "actions team" or "copilot team" 25 | 26 | ### START OF DISCUSSION POST 27 | 28 | TITLE: ${post.title} 29 | TEAM: ${post.repository.humanName} 30 | 31 | ${post.body} 32 | 33 | ### END OF DISCUSSION POST 34 | ``` -------------------------------------------------------------------------------- /quick-ref.md: -------------------------------------------------------------------------------- 1 | # How GitHub Engineering communicates: Quick reference guide 2 | _(Community version, lightly edited, primarily to remove internal URLs and references)_ 3 | 4 | This document is a quick-reference companion to the full ["How GitHub Engineering communicates" document](./how-github-engineering-communicates.md). For more details about anything noted here, as well as background/purpose and usage information, please see that full set of guidance. 5 | 6 | 7 | ## Guiding principles 8 | 9 | Overall, the way we communicate as an Engineering organization is informed by the following principles (fully defined in the ["How GitHub Engineering communicates" guidance](./how-github-engineering-communicates.md)): 10 | 11 | * Be asynchronous first 12 | * Write things down 13 | * Make work visible and overcommunicate 14 | * Prefer GitHub tools and workflows 15 | * Embrace collaboration 16 | * Foster a culture that values documentation maintenance 17 | * Communicate openly, honestly, and authentically 18 | * Strive for inclusivity 19 | * Use emoji and animated GIFs 20 | * Remember practicality beats purity 21 | 22 | ## Communications channels 23 | 24 | In brief, here's which communication channel we prefer for which purpose (further explained in the ["How GitHub Engineering communicates" guidance](./how-github-engineering-communicates.md)): 25 | 26 | ## Chat 27 | 28 | 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. 29 | 30 | ## GitHub 31 | 32 | **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. 33 | 34 | **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. 35 | 36 | **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. 37 | 38 | **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. 39 | 40 | **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. 41 | 42 | **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. 43 | 44 | ## Google Docs 45 | 46 | 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. 47 | 48 | ## Live meetings 49 | 50 | 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. 51 | 52 | ## Video recordings 53 | 54 | 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. 55 | 56 | ## Email 57 | 58 | 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. 59 | 60 | -------------------------------------------------------------------------------- /tips-for-leaders.md: -------------------------------------------------------------------------------- 1 | # How GitHub Engineering communicates: Tips for leaders 2 | _(Community version, lightly edited, primarily to remove internal URLs and references)_ 3 | 4 | Overall, the way we communicate as an Engineering organization is informed by the following principles (fully defined in the ["How GitHub Engineering communicates" guidance](./how-github-engineering-communicates.md)): 5 | 6 | * Be asynchronous first 7 | * Write things down 8 | * Make work visible and overcommunicate 9 | * Prefer GitHub tools and workflows 10 | * Embrace collaboration 11 | * Foster a culture that values documentation maintenance 12 | * Communicate openly, honestly, and authentically 13 | * Strive for inclusivity 14 | * Use emoji and animated GIFs 15 | * Remember practicality beats purity 16 | 17 | This document contains a brief set of further expectations for leaders on how to set an example and create an environment on their team(s) that promotes these principles. 18 | 19 | ## Invest in psychological safety 20 | 21 | Start here 👆. If there's one thing you can do to foster stronger asynchronous practices on your team, it's to be intentional about [creating psychological safety](https://rework.withgoogle.com/en/guides/understanding-team-effectiveness#introduction). Be open to feedback, admit your mistakes, and show vulnerability. By cultivating an inclusive environment in which your team members feel safe to take risks, share ideas, voice concerns, and provide feedback, all without fear of retribution, you'll empower them to be able to work more independently on the schedule that works best for them, and they won't be held up waiting to ask for your approval. Plus, being open and able to discuss the hard things with each other means we'll always be growing and improving. 22 | 23 | Ways to get started: 24 | 25 | * Be open about your strengths, preferences, and areas of opportunity to help your team members feel comfortable being human too (create a [Human User Guide](https://github.com/matthewmccullough/human-interaction-templates/blob/master/human-user-guide.md) and link to it from your Slack profile, and encourage your team to do the same 26 | * Be open to feedback, admit your mistakes, and show vulnerability 27 | * Prioritize and be fully present in 1:1s, and let your team members drive the agenda (it's their time) 28 | * [Write like a human](./how-github-engineering-communicates.md#communicate-openly-honestly-and-authentically) and be as transparent in communications as possible, and consider creating an FAQ for anticipated questions (remember it's better to say "I don't know" or "I can't answer that right now" than to pretend the question doesn't exist) 29 | * Keep your virtual door open and proactively seek out feedback (send out congrats messages for big ships when you have a few minutes between meetings; pick a few team members to review comms before sending and implement a change based on their feedback; ask more direct questions 1:1 like "What support would be helpful?" or, "What's the biggest risk I'm not seeing right now?") 30 | 31 | ## Be explicit about expectations 32 | 33 | As a team, collaboratively author a set of agreements, captured as Markdown files within your team's repo, outlining your agreed-upon working and communication styles, including anticipated response times and preferred channels. This not only ensures everyone is on the same page, but sets a baseline for what's expected of one another – everyone should be clear on what you expect from them, what they can expect from each other, and what they can expect from you. This activity is especially important when spinning up a new team or reorganizing an existing one, but it's also a good practice to periodically revisit these agreements to ensure they continue to reflect the team's shared values and evolving workflows. 34 | 35 | Ways to get started: 36 | 37 | * Review the ["How GitHub Engineering communicates" guidance](./how-github-engineering-communicates.md) and talk together about what parts of our "common API" for Engineering communications work best for your team, and which might differ 38 | * Talk with your team about the number of standing meetings on their calendars and be explicit about which ones they're expected to attend live and which they can catch up on asynchronously, so they feel more empowered to take control of their time 39 | * Schedule and honor no- and low-meeting days (like Days of Learning and No Meeting First Fridays) by rescheduling any non-urgent meetings 40 | * Agree on and maintain a single source of truth for team decisions (bonus points if it's easy to find and search through) 41 | 42 | ## Optimize for the information retriever 43 | 44 | Rather than optimizing for immediate information exchange, pause to ask yourself how easy you are making it for someone to come along behind you to understand what you are doing and why, so they can contribute to the conversation. It's essential that we write things down – especially the "why" and the "how" of decisions – in the most durable, searchable, and discoverable medium possible. This is slightly more work up front for the one knowledge creator, but optimizing for the long-tail of knowledge retrieval will save countless hours for all the knowledge recipients. Think of it kind of like removing an N+1 in a heavily trafficked code path: The initial re-write takes time, but not as much as it saves in the long run. 45 | 46 | Ways to get started: 47 | 48 | * Build time to update documentation into team work plans (and if a document's maintenance outweighs its benefits, delete or simplify it) 49 | * Block focus time on your calendar for writing and reading so you can preserve synchronous team time for high-impact conversations and informed decision-making 50 | * Ensure every meeting has an agenda document (bonus points if it's a discussion post) that's shared ahead of time to collect input from team members who can't attend live, so their voices can be heard during the call (and be sure to post pass-down notes after the call, too!) 51 | * Make any big announcements ahead of (not during) synchronous meetings (this ensures the whole team has access to the announcement, even if they can't attend the call, and they have time to process the information and collect their questions) 52 | 53 | ## Make more of your work visible 54 | 55 | The best way to work in the open and to make that work visible is to use GitHub tools and workflows. [So embrace your inner engineer and default to working within GitHub](https://ben.balter.com/2023/01/10/manage-like-an-engineer/), whenever possible and practical. By working more in the open, you'll naturally capture and expose processes, better preserving institutional knowledge, empowering others to learn through observation, and setting the standard for organizational culture and values. Plus, you'll reduce time spent on status updates, as your team can more easily understand what you're working on and why, plus provide feedback along the way. Of course, there's no need to track every one of your administrative tasks in a team repo; surface the important work (like decisions where you want input, or longer-running issues for which your team is looking for regular updates). 56 | 57 | Ways to get started: 58 | 59 | * Set up and maintain a leadership team project board so your team has better insight into what's currently in flight 60 | * Seek feedback before decisions are made (rather than asking for feedback on a decision); invite collaboration directly on your issues, discussions, Markdown files, and pull requests; and document how you incorporate the team's feedback (to show you're willing to act on it, and thus it was worth their time contributing) 61 | * Use queries in GitHub to automate team status updates and weekly reports as much as possible and free more of everyone's time (if someone's already reported a status in GitHub, they shouldn't have to repeat it in Slack or in a meeting) 62 | * Mark any information in your own weekly report that's more sensitive and not intended for broad consumption as "private", and then share the "public" version of your report back out with your organization in a discussion post 63 | 64 | --------------------------------------------------------------------------------