How the GitHub Docs team uses GitHub Projects

It’s been said that documentation is like a love letter to your future self.

If that’s the case, then GitHub Docs are love letters to our 100 million developers who turn to them everyday for help and support. Whether it’s a student who wants to sign up for an account or a seasoned senior developer who needs to set up GitHub Enterprise Server, Docs meets each person where they are and in the language they speak (and code in, too).

Here at GitHub, we’re committed to helping organizations supercharge productivity and innovation. To that end, let’s explore why and how our Docs team uses GitHub Projects to manage their 2,396 open source Docs articles (or 18,545 articles when counting all languages and versions)—which get 900,000+ daily pageviews by 350,000+ daily users.

So much complexity. Enter, GitHub Projects

Our 42-person Docs team is fully remote and spans the globe, with members in North America, Australia, Europe, and Africa. For such a diverse team working on such an expansive initiative, having a robust project management tool is mandatory. Fortunately, GitHub Projects works beautifully. We use it to track our biweekly work cycles, prioritize and plan work, make work visible across the organization, triage issues, and manage releases.

Workflows for the win

As you might imagine, Docs articles involve quite a bit of versioning. Some articles are available in all versions, some are GitHub.com-only, while others are GitHub Enterprise Server-only. Additionally, different articles have different internal conditionals, where a single paragraph or even a word may be relevant in some versions but not others. This adds complexity for our team when it comes to management.

But GitHub Projects makes the complexity a breeze by enabling different types of workflows. These workflows (we use both GitHub Actions workflows and built-in workflows) allow us to accurately capture all that’s needed. This is especially lifesaving for launches. For each launch, we may need to create more than 50 new articles (while a normal day may involve 15 to 20 pull requests and several updates). Enabling different workflows keeps everything organized and on track.

Got labels?

Additionally, labels can be added to issues, so it’s easy to know at a glance which features an issue is tracking and what it needs from the team. These labels are especially helpful for the review process—our team adds a label for external contributors, another for internal contributors, and so on. Each time we add a new label, a GitHub Actions workflow is triggered. For example, when we add our “ready-for-review” label, a pull request is automatically added to our review board. Also, team members can use labels to create their own views and insights without messing up the workflow.

Virtuous visuals

With GitHub Projects, our team members can enable different views of the boards—allowing easy visualization and organization for everyone. For instance, our team has large sets of managers and writers. These two groups use different project board views that work better for their specific roles. The same is true for people on subset teams or for employees from an entirely different part of the company. With different ways to visually customize the boards, everyone can instantly see what they need or want to see, and nothing more. This makes getting up to speed a snap. Also, with the @me functionality, each team member can see the tasks that are pertinent to them, which allows people to instantly know what they need to know.

Like peanut butter and jelly: GitHub Projects + GitHub Actions

For our team, one of the nicest things about using GitHub Projects is it can be easily paired with other GitHub products, increasing its capabilities. For instance, we add in GitHub Actions to customize and scale workflows. This tool, along with the Projects API, enables us to take full control of our projects. GitHub Actions also allows levels to be added to tracking issues, and then subsets of the team (such as Docs content, Docs engineering, Docs strategy, and managers) can triage issues with their own workflows. In general, because GitHub enables integration throughout the platform, the tools and capabilities we need are embedded throughout—making the experience seamless.

The bottom line

We want to save time and get to the fun stuff. GitHub Projects fits us like a glove and provides an experience that’s so intuitive, we barely even notice it. You know what that means for us, right? More time to write more love letters to developers everywhere.

Written by

Steve Guntrip

@stevecat