Your GitHub presence is as much a part of your brand and developer experience as is your own developer portal. And that applies even if your organization doesn't use GitHub.
Here are five things you can do to improve how you serve developers through your GitHub organization.
1. Get the basics right
Your GitHub org serves at least two audiences:
- Developers who already work with you.
- Developers who don't know you and might like to.
It's natural to think of GitHub only as a tool to help manage our development work. But your GitHub presence plays a second, just as important, role.
Whether you're an open source project, a vendor with a commercial product, or some mix of both, your GitHub presence will be the first way that many developers encounter what you do.
What they need from your GitHub org is to learn which problems your code solves, who's who, whether they can trust you, and how to get started.
You can go a long way simply by filling out your GitHub org profile. In particular, use the description to set out why your company or project is on GitHub and what people can expect.
If your company has a GitHub Enterprise account you can add an extra touch of reassurance with "Verified" status.
Here's a simple way to test if you've got the basics right. Find a handful of developers who don't know your company or project, ask them to look at your GitHub org page, and then have them tell you individually what they learned. If most of them came away with the right impression, then your GitHub org profile information is probably doing its job.
2. Org README
Displaying a repo's README on its GitHub overview page is something we take for granted and yet it is a huge win. It gives the repo owner huge scope to shape how people engage with their code. And when the README is done right, showing it on the repo page opens that code to vastly more people.
Recently, GitHub introduced org READMEs. While every other recommendation in this article is important, they all stand in the shadow of the org README.
Effectively, now the only limitation on how you present your org is whatever you can put into a Markdown file. That means you need to establish your own limits by defining what you want to achieve with your organization's GitHub presence.
Do you want to win customers for a commercial product? Are you looking to onboard new contributors to an open source project? Perhaps your primary aim is to present your company's engineering prowess to the world and, so, attract potential recruits.
Take a look at GitHub's own org page. At the time of writing, they have a single image that clearly establishes this as a "GitHub the company" space within "GitHub the code hosting website". Most importantly, though, the text is organized to be skimmable, with links to important aspects of their GitHub presence, along with a final link to more reading material.
Use your org README to help visitors understand how they can navigate and use your GitHub presence and to communicate something of who you are as an organization. Link to your get started documentation, help people navigate your repos, set out how to get support.
3. Pin repos
By default, GitHub orders your org's repos by when they were last updated. So at least that means the list won't be topped by an abandoned JQuery library someone forked a few years back.
However, it's likely there are a few repos that most developers coming to your page will want more than others. Let's say you're selling an API based SaaS product and offer client libraries for different languages then those might be the repos most people want.
Pin the repos that most people will want, not forgetting to also link to them in your org README. That way, they'll be easy to find and you can make sure that visitors don't have wade through repos that are only of interest to your team.
Trust is hard won. Your GitHub org page might be the first time that someone has encountered your company or project. Even if not consciously, most people will scan your GitHub presence for signs of whether they can trust you.
One simple way to enhance trust is to make sure the "People" section of your org page shows who is involved. Real, contactable people putting their own reputations on the line is a signal of your organization's credibility.
Of course, not everyone needs to or will want to be public and it's important to remove people no longer associated with your org.
5. If you're not on GitHub, tell developers where to find you
Not every company or open source project uses GitHub. But that doesn't mean you should neglect your GitHub presence.
Many developers look first on GitHub. So, you risk that they'll find nothing or that they'll find someone else where you should be. At the very least, use an org README to tell people where to find you for real.
GitHub has become a first step for many developers seeking out new tech to work with. However you use it for your own organization, it takes relatively little effort to make sure your org page is helpful to those developer who might want to work with you.