How GitHub Uses GitHub: Communicating with Issues

From product design mocks to user help content, GitHub teams use GitHub to build just about everything—and they're often collaborating across different timezones. As we continue to build products that fit all of your team's use cases, we're sharing insights into what's worked (and what hasn't worked) for our team's unique challenges in a new series.

In this session, you'll get the training we give new team members when they join GitHub. We'll cover strategies for clear communication, visual structure in issue comments, and how to facilitate discussion. These strategies are integral to how our team uses InnerSource and may help your team's InnerSource approach.

Transcript

1. the best way to build and ship software
   Communicating with Issues
   How GitHub uses GitHub
   

   View Slide

2. the best way to build and ship software 2
   Cynthia Rich
   @crichID, Manager of Training
   

   View Slide

3. the best way to build and ship software
   A few logistics
   3
   ▸ 40 minutes presentation, 10 minutes Q&A
   ▸ Please ask questions in the GoToWebinar Q&A panel
   ▸ Recording
   ▸ Yes, we are! It will be sent via email after the presentation.
   ▸ Additional Questions
   ▸ services@github.com
   

   View Slide

4. the best way to build and ship software
   In this session, we will focus on the communication
   patterns we use here at GitHub. This includes:
   ▸ Organizing people and projects
   ▸ Organizing Issues and Pull Requests
   ▸ Optimizing your written communication
   ▸ Providing visual structure to support your ideas
   4
   Our goals
   

   View Slide

5. the best way to build and ship software 5
   How we communicate
   

   View Slide

6. the best way to build and ship software 6
   Organizing people
   

   View Slide

7. the best way to build and ship software
   How we think about teams ...
   7
   Organizational Teams
   services
   services-engineering
   services-tools
   services-training
   services-operations
   Project Teams
   project-lily-spider
   Affinity Teams
   blacktocats
   Location Teams
   emea
   north-carolina
   }
   

   View Slide

8. the best way to build and ship software
   Liberal @ mentions
   8
   ▸ Filtering emails is an art form
   ▸ Direct mention vs. team mention
   ▸ We unsubscribe
   

   View Slide

9. the best way to build and ship software
   Organizing projects
   9
   

   View Slide

10. the best way to build and ship software
    Key ingredients of a project
    10
    ▸ README.md
    ▸ CONTRIBUTING.md
    ▸ ROADMAP.md
    ▸ ISSUE_TEMPLATE.md
    ▸ PULL_REQUEST_TEMPLATE.md
    

    View Slide

11. the best way to build and ship software 11
    Flexible project boards
    

    View Slide

12. the best way to build and ship software 12
    Organizing issues and pull requests
    

    View Slide

13. the best way to build and ship software
    Using assignees
    13
    ▸ Assignees are used to indicate who is responsible
    for the next step.
    ▸ Changes to assignees are documented in the Issue
    or Pull Request
    ▸ Every discussion has an assignee
    

    View Slide

14. the best way to build and ship software 14
    Another benefit of assignees
    

    View Slide

15. the best way to build and ship software
    Labels should fit the needs of your project
    15
    Your perfect set of labels
    

    View Slide

16. the best way to build and ship software 16
    The power of the written word
    

    View Slide

17. the best way to build and ship software
    We write A LOT
    17
    GitHubbers communicate differently:
    ▸ We focus on inclusive communication
    ▸ We rely heavily on async communication
    ▸ We believe in crafting communication for our future
    selves
    

    View Slide

18. the best way to build and ship software 18
    

    View Slide

19. the best way to build and ship software
    What are you trying to accomplish?
    19
    Three questions ...
    

    View Slide

20. the best way to build and ship software
    Who are you trying to reach?
    20
    Three questions ...
    

    View Slide

21. the best way to build and ship software
    What action do you want taken?
    21
    Three questions ...
    

    View Slide

22. the best way to build and ship software
    ▸ Perception
    ▸ Investment
    ▸ Support
    22
    Always consider your reader
    

    View Slide

23. the best way to build and ship software
    ▸ BLUF
    ▸ tl;dr
    ▸ RACI
    ▸ SCIPAB
    23
    Useful Techniques
    

    View Slide

24. the best way to build and ship software 24
    BLUF
    

    View Slide

25. the best way to build and ship software 25
    tl;dr
    tl;dr is an acronym for Too Long, Didn’t Read.
    It is typically used at the beginning or end of a long post
    to provide a summary for the reader to gauge the level
    of investment they have in the long form content.
    

    View Slide

26. the best way to build and ship software 26
    RACI
    Code RACI Summary Details
    R Responsible “The doer” The individual who actually completed the
    task. This is person is responsible for
    action/implementation of the deliverable.
    A Accountable “The buck stops here” The individual who is ultimately
    accountable for the correct and thorough
    completion of the deliverable.
    C Consult “In the loop” The individual(s) to be consulted prior to a
    final decision or action. This is two-way
    communication.
    I Inform “Keep in the picture” The individual(s) who need to be informed
    after a decision or action is taken. This is
    one-way communication.
    

    View Slide

27. the best way to build and ship software 27
    SCIPAB
    

    View Slide

28. the best way to build and ship software 28
    

    View Slide

29. the best way to build and ship software 29
    # markdown
    

    View Slide

30. the best way to build and ship software 30
    Our favorite markdown features
    ▸ Links & cross references
    ▸ Tables
    ▸ Headers
    ▸ Bold & italics
    ▸ Quotes
    ▸ Images
    ▸ Code blocks
    ▸ Task lists
    ▸ Dropdowns
    

    View Slide

31. the best way to build and ship software 31
    Cross references and links
    

    View Slide

32. the best way to build and ship software 32
    Tables
    

    View Slide

33. the best way to build and ship software 33
    Basic formatting
    

    View Slide

34. the best way to build and ship software 34
    Quoting text
    

    View Slide

35. the best way to build and ship software 35
    Images
    

    View Slide

36. the best way to build and ship software 36
    Code blocks
    

    View Slide

37. the best way to build and ship software 37
    Task lists
    

    View Slide

38. the best way to build and ship software 38
    Simple dropdowns
    

    View Slide

39. the best way to build and ship software
    The Ultimate Guide to Markdown
    39
    

    View Slide

40. the best way to build and ship software 40
    A few more helpful tips
    

    View Slide

41. the best way to build and ship software 41
    Reactions and emoji voting
    

    View Slide

42. the best way to build and ship software 42
    Indicating the scope of the ship
    

    View Slide

43. the best way to build and ship software 43
    A whole new level
    

    View Slide

44. the best way to build and ship software
    ▸ July 25: Communicating with issues
    ▸ August 22: Communicating with remote teams
    ▸ September 26: Managing your teams
    ▸ October 24: Managing your projects
    ▸ November 28: Writing documentation for your
    projects
    Sign up at services.github.com
    44
    How GitHub Uses GitHub
    

    View Slide

45. the best way to build and ship software
    Questions?
    45
    

    View Slide