How the Services team uses GitHub

If you’re writing code, a repository is an obvious place to manage your work. But what about when the team’s primary deliverable is not software? At GitHub, the Professional Services team helps customers get set up with GitHub Enterprise and trains people how to use Git and GitHub. We use GitHub extensively to efficiently and transparently communicate, schedule and prioritize. We hope how we use GitHub will help your team use the platform for more than just code.

Services team repository as our main interface for interaction

Most teams at GitHub have a team repository with a README.md file that introduces the team and explains the team’s main responsibilities. Our Services team’s repository shows our offerings and introduces the members of our team.

Our README provides a clear path forward for teams who want to utilize our services by listing our offerings and showing who to reach out to if help is needed. We provide specific team handles for people to mention us with GitHub’s @mention feature. By mentioning a specific team they can reach the subset of the team they need.

This way, different team members can respond to their respective team handles. Some teams at GitHub rotate who is responsible for checking their team’s mentions on a weekly basis. This lets some team members have stretches without distraction while the team is still responsive to GitHubbers outside of their team. We have streamlined many processes to utilize @mentions with GitHub’s notifications instead of relying solely on email correspondence.

In our README, we also have linked Markdown files that document our services. We have files that document how we work, including everything from checklist-formatted Markdown files for onboarding new team members to guides on how to configure LDAP for our customers on GitHub Enterprise. Our team repository provides ample information for people to do their jobs.

Coordinating customer engagements

GitHub Issues, Pull Requests and Notifications are at the heart of coordinating, delivering, and reviewing the Services team’s engagements with customers. We use a link that has our engagement Issue template as the body parameter of the URL. This creates a checklist as the top comment of a newly created issue. We coordinate with Sales, Finance, and Legal by opening issues in their team’s respective repositories.

Once an engagement is set and ready to be delivered we open a Pull Request to track delivery tasks and notes. We create a file called retrospective.md in a /engagements folder in the repository to open the Pull Request. We then use the top comment of our Pull Request to track any bugs, follow-up tasks for after the engagement, and leave notes for sales to take over. We add comments to the Pull Request for each day’s notes to keep everyone on the team in the loop.

When we complete the engagement we write our retrospective. Many different teams at GitHub know about this folder and check in on customer feedback by visiting this /engagements folder and reviewing the retrospective files. We use Pull Request comments to add final details like our expenses and mention the teams needed to close out any outstanding tasks. The process lets us have a great historical document of our conversations instead of the details getting lost in people’s email.

Team decisions and transparency

On the GitHub Professional Services team, we try to ensure the decision-making process and our team’s initiatives are as collaborative and transparent as possible. We open an issue to discuss any topic that needs our attention. We try to default to having conversations in the open and with a URL.

Transparent conversation is especially necessary as a geographically-distributed team. This pattern permits others who are on Services engagements to get context when they finish their engagements and catch up on their notifications. It also lets people understand the why of a decision even years after the decision occurred.

We often have lengthy discussions about which path to chose, and because we’re a diverse team, we hear many different approaches. Our internal focus is to get to a point where we can move forward with an option to test, and refine the path forward as we get more information about what works best.

Weekly radar meetings (standup)

Each Monday, we create an issue that we use as our standup meeting. We add our availability for the week and the main items we will be focusing on. We get together for a 30-minute video chat session to collaborate on the week’s activities and to spend some face-to-face time together. People add updates to their activities throughout the week in the radar issue. This helps us stay connected as a distributed team.

How we use pull requests for non-code related changes

The Services team’s uses of Pull Requests are varied. We tend to think of a pull request as shipping some change or accomplishment into our organization. We open pull requests to change our README, to track an engagement we are on and to propose future plans for the team. The pull request process enables us to get feedback from our team members while also tracking our major accomplishments. We use GitHub’s checklist feature to track outstanding tasks for any deliverable (including this blog post).

Pull requests do a great job of showing how a document evolved as well as making that evolution a collaborative process. By editing files in a pull request, we can see how our thinking has changed over time or how our organization has grown. I attended a great session at OSCON Amsterdam about how New Relic uses Pull Requests for non-code deliverables as varied as discussing company policy changes to documenting infrastructure. Many of the companies that use GitHub discover how the simple @mention and notification tools can transform workflows and company culture.

Collaboration is at the heart of GitHub

At the heart of GitHub is a toolset that empowers developers through tracking change and enabling collaboration. The Services team at GitHub uses these tools as an integral part of their work to help move the company forward. How does GitHub help your team be more collaborative and productive?

The Services team is hiring for multiple positions. Check out the job board and see how you can help us enable companies to create great things with GitHub. If your team needs help getting the most out of GitHub you can visit our website to see our offerings.

Written by

Matt Duff

@mattcantstop