Create a home for your community with GitHub Discussions

2024-07-31 01:40:54

GitHub Community-in-a-box provides the tooling, resources, and knowledge you need to build internal communities of learning at scale with GitHub Discussions.

Incorporating new technology into your organization’s workflow involves more than just understanding the tool—it requires a culture shift towards community. By creating a destination for inspiration and knowledge sharing, you can enable your teams and individuals to accomplish more together.

GitHub Discussions is a dedicated space for conversations. It decreases the burden of managing active work in issues and pull requests by providing a separate space to host ongoing discussions, questions, and ideas. We use GitHub Discussions to enable dialogue among tens of thousands of community members via the GitHub Community Discussions, to host a private GitHub maintainers community, and to support team-internal conversations.

We created GitHub Community-in-a-box, packaging up tooling, resources, and knowledge, for organizations of all sizes, to enable our customers to build internal communities of learning at scale using GitHub Discussions.

Let’s take a look at ways to manage GitHub Discussions for your community, best practices for moderation, tips for promoting healthy engagement and content creation, and ideas for going the extra mile for your community.

When might GitHub Discussions be useful for you?

You can use GitHub Discussions to chat about big-picture ideas, brainstorm, and develop a project’s specific details before committing it to an issue, which can then be scoped. GitHub Discussions is useful for teams in a number of scenarios:

You are in the discovery phase of a project and are still learning which direction your team wants to go in.
You want to collect feedback from a wider community about a project.
You want to keep bug fixes, feature requests, and general conversations separate.
You want to measure interest in new ideas and gauge community opinion using polls.

To learn more about GitHub Community-in-a-box and get started with GitHub Discussions, check out this guide, download our community checklist, and don’t miss GitHub Community Discussions Announcements to keep up with new features, events, beta programs, surveys, and more!

Based on what we’ve learned through our community, we have a few recommendations that will help yours thrive:

1. Grant helpful community members moderator or maintainer permissions to help drive a healthy community, as well as moderate and guide your community space.

Screenshot of the menu from which you can promote a member to admin.

2. Create categories.

Think about the topics your community will likely discuss and group them into the most relevant categories. This will ensure your community stays neat and organized. GitHub Discussions come with a few default categories:

Screenshot of the list of default categories for GitHub Discussions. They are: announcements, general, ideas, polls, Q&A, and Show and tell.

But it takes seconds to set up additional ones, as you can see in the example below:

Screenshot of the form to add a new category to GitHub Discussions. The fields include category name, description, and discussion format.

3. Leverage GitHub Discussions category forms.

You can encourage community members to include specific, structured information in their discussions by using discussion forms in your repository. Let’s make a basic category form for our Knowledge base category we created in the last step:

Screenshot of the metadata for creating a basic category form.

Once you commit the change and start a new discussion for the Knowledge base category, you will see your category form in action:

Screenshot of a new discussion being started using the "Knowledge base" category form created in the previous step.

4. Create + add labels to discussions to organize them more granularly.

This will enable your community to filter by relevant labels and will also create more meaningful data insights for your community. Similar to categories, GitHub Discussions comes with a set of default labels:

Screenshot of the list of default labels for GitHub Discussions. They are: bug, documentation, duplicate, enhancement, good first issue, and help wanted.

But let’s create a few additional ones that meet our community’s needs:

Screenshot of the form for creating a new label.

5. Pin important discussions.

You can pin a discussion for the repository as I have done here with my GitHub Discussions resources post:

Screenshot of the Community-in-a-Box discussions page, with discussions titled "Welcome to community-in-a-box discussions!" and "GitHub Discussions resources" pinned to the top of the page.

Or to a specific category:

Screenshot of a discussion pinned to the landing page of the "Knowledge base" category.

The globally pinned discussions will be shown in addition to the discussions pinned to a specific category.

Deep dive: GitHub Discussions moderation

Moderation of a community is incredibly important to the overall community health (see the GitHub Docs for detailed guidance). The following best practice tips will help you maintain an active and healthy community:

1. Reply to posts in assigned categories.

Replying to questions and comments within a reasonable amount of time (such as in this example) is important to ensure community members find value in your discussions instance, and will encourage them to return and actively contribute to your community. In order to manage the workload we recommend assigning dedicated moderators per category depending on the new discussions volume created per day.

A user "santoshvandari" has replied to a discussion.

If a question has been resolved, mark the best comment as an answer (see the below example from the GitHub Community Discussions).

The comment on a discussion that has been marked as answer is highlighted in green and labeled as the answer.

This will aid community members in finding solutions to their questions and will motivate contributions as community members with the highest number of marked answers will appear in the “Most helpful” leaderboard of your GitHub Discussions community.

3. Manage spam.

Spam is unlikely to occur in an internal community, however, it may happen that community members post comments that are off-topic or engage in heated discussions. We recommend you warn offenders and hide their discussions. In cases of repeat abuse, you may want to consider blocking someone from your community completely.

We recommend adding a Code of Conduct to define community standards, signal a welcoming and inclusive project, and outline procedures for handling abuse. When you add a Code of Conduct like the Contributor Covenant Code of Conduct to your repository, it will automatically be linked in your discussions instance as well once you commit the file.

The code of conduct for the Community-in-a-box repository.

Screenshot of the sidebar of a repository with its various links. A link to the code of conduct is near the bottom.

You may want to consider creating other community health files depending on your specific needs.

4. Lock or unlock discussions.

This is a valuable feature for scenarios when you want to keep a discussion in your community in “read-mode” only but don’t want to enable community members to leave further comments (for example, you requested feedback for a feature but collected enough information). Have a look at this post from the GitHub Community Discussions for reference:

Screenshot of a discussion that has been locked. This is indicated by the presence of a gray "locked" icon underneath its title.

You have the option to edit or delete comments in case community members post inappropriate content or confidential information.

Screenshot of a comment with the menu options pulled up (access by clicking the three dots at the top of the comment.) The options include edit, hide, delete, report content, and block user.

6. Recategorise posts.

Community members may accidentally post discussions in the wrong category. To keep your community clean and tidy, we recommend you move posts to the correct category.

Screenshot of the change category menu.

7. Apply labels.

We recommend creating a variety of labels with regards to the format (for example,question, feature request, bug report, feedback) as well as topic (for example, GitHub Actions, GitHub Copilot, GitHub Codespaces) of discussions within your community. The ability to filter by labels will ease moderation, help community members find the right answers, and enhance the data you collect. To gain inspiration, take a peek at the labels we use in the GitHub Community Discussions.

Screenshot of the list of labels available in the community-in-a-box repository.

In the section above we described the basics of community management. If you want to take it a step further and provide the best experience for community members, here are a few more suggestions:

When someone new joins your community, make an effort to send them a personal welcome message. You can even start an “Introduce Yourself” thread (tip: pin the thread globally or in the right category) for community members to post little paragraphs about themselves and to make their first discussions contribution as easy as possible.

Screenshot of a discussion by use "ettaboyle" welcoming new members and inviting them to introduce themselves.

2. Look for community members who are actively participating and posting great answers— appreciate and motivate them.

Each community has certain members who go above and beyond to be helpful to others. They are the pillars of your community. To help retain your top contributors and to keep them motivated, show them some love. You can do so for example by highlighting them in a discussions post. The Most helpful leaderboard will show your community’s top contributors over the past 30 days:

Screenshot showing six users that have been the most helpful in the last 30 days.

Use Discussions insights to understand the contribution activity, page views, and growth of your discussions community. In addition, you can see what is most popular in your categories and track the top viewed posts every week. This information can help you craft content based on topics community members seem to struggle with or are most interested in.

Screenshot of four graphs available on the community insights tab.

4. Create content to generate engagement and enhance your community knowledge base.

Consider crafting monthly check-ins, AMAs (Ask Me Anything), product update announcements, or blog posts written by subject matter experts.

Screenshot of a discussion called "Using GitHub apps"

GitHub is a community of communities, including yours.

We hope these resources help you build and manage your own online communities using GitHub Discussions!

Additional resources for launching and managing your own GitHub Discussions community

Written by