$30 off During Our Annual Pro Sale. View Details »

How GitHub Uses GitHub: Communicating with Issues

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.

Cynthia Rich

July 25, 2017
Tweet

More Decks by Cynthia Rich

Other Decks in Technology

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
    [email protected]

    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