📦 Community-in-a-box

[ossanna16]

🚀 Launch your own Discussions community immediately!

Created by GitHub community professionals, Community-in-a-box packages up tooling, resources, and knowledge, for organizations of all sizes to set up internal communities at scale.

💻 Who is it for?

• Developers
• Enterprise admins
• Team leads & managers
• Executive stakeholders
• Product, project & program managers
• Facilitators & coordinators
• Students

💡Why Community-in-a box?

GitHub is a community of communities and a major proponent of InnerSource principles, and wants to provide all the resources you need to build and manage your own internal online communities using GitHub Discussions, a built-in free product that supports community building & management (GitHub Community Discussions is where we use our own product to foster the GitHub Community) available within all GitHub organizations and repositories.

📦 What’s included in the “box”?

• GitHub Discussions enablement: How-to use GitHub Discussions to foster InnerSource principles and build + manage internal communities of learning at scale
• Resources: Access to a Discussions repository you can clone to get started with your community in no time (work in progress)
• Knowledge base: Best practice resources, guides, community-related content

💡 How to use this document

The goal of this guide is to provide an overview of GitHub Discussions, and help you set up and manage your own internal GitHub Discussions community.

❓What is GitHub Discussions?

(Source: GitHub Discussions; see also “What is GitHub Discussions? - A complete guide”)

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.

🤔 Why use GitHub Discussions?

(Source: GitHub Documentation)

• 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

See Discussions in production! 🌐 Blog post: How five open source communities are using GitHub Discussions

📁 Enabling GitHub Discussions on your repository

Repository owners and people with write access can enable GitHub Discussions on their public and private repositories (⬅️ the link will guide you to the GitHub Docs and help you enable Discussions on your repo). The visibility of a discussion is inherited from the repository the discussion is created in.

💻 Enabling GitHub Discussions on your organization

Organization owners can enable GitHub Discussions for their organization (⬅️ the link will guide you to the GitHub Docs and help you enable Discussions for your org). When you enable organization discussions, you will choose a repository in the organization to be the source repository for your organization discussions. You can use an existing repository or create a repository specifically to hold your organization discussions. Discussions will appear both on the discussions page for the organization and on the discussion page for the source repository.

⁉️ Repository- vs. organization level Discussions

(Source: GitHub Documentation)

When you enable organization discussions, you will choose a repository in the organization to be the source repository for your organization discussions. You can use an existing repository or create a repository specifically to hold your organization discussions. Discussions will appear both on the discussions page for the organization and on the discussion page for the source repository.

Permission to participate in or manage discussions in your organization is based on permission in the source repository. For example, a user needs write permission to the source repository in order to delete an organization discussion. This is identical to how a user needs write permission in a repository in order to delete a repository discussion.

You can change the source repository at any time. If you change the source repository, discussions are not transferred to the new source repository.

🏆 Overview: Managing a successful internal Discussions community

The following recommendations will help your community thrive 🎉

• 🎤 Grant helpful community members moderator or maintainer permissions to help drive a healthy community, as well as moderate and guide your community space.
• 📁 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.
• 🗒️ Leverage Discussions category forms: You can encourage community members to include specific, structured information in their discussions by using discussion forms in your repository. To gain inspiration have a look at the Discussions category forms the Community Engagement created.
• 🏷️ 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.
• 📌 Pin important discussions: You can pin a discussion for the repository or organization. You can also pin a discussion to a specific category. The globally pinned discussions will be shown in addition to the discussions pinned to a specific category.
• 🎙️ Moderate discussions: You can promote healthy collaboration by marking comments as answers, locking or unlocking discussions, converting issues to discussions, and editing or deleting comments, discussions, and categories that don't align with your community's code of conduct.
• 📈 View data for your Discussion: You can use discussions insights to help understand the contribution activity, page views, and growth of your discussions community.

💬 Deep dive: Discussions moderation

Moderation of a community is incredibly important to the overall community health. The following best practice tips will help you maintain an active and healthy community:

• ✍️ Reply to posts in assigned categories: Replying to questions and comments within a reasonable amount of time 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.
• ✅ Mark comments as answers: If a question has been resolved, mark the best comment as an answer (see this example from the GitHub Community Discussions). 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 Discussions community.
• ⛔ 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.
• 🔐 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 (example: you requested feedback for a feature but collected enough information). Have a look at this post from the GitHub Community Discussions for reference.
• 🗑️ Edit or delete comments: You have the option to edit or delete comments in case community members post inappropriate content or confidential information
• ⏪ Recategorise posts: Community members may accidentally post discussions in the wrong category. In order to keep your community clean and tidy, we recommend you move posts to the correct category.
• 🏷️ Apply labels: We recommend creating a variety of labels with regards to the format (example: question, feature request, bug report, feedback) as well as topic (example: Actions, Copilot, 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.

🛣️ Going the extra mile: Engagement & content creation

In the sections 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:

• 👋 Welcome new community members: 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.
• 💟 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. In order to help retain your top contributors and to keep them motivated, show them some love ♥️. You can do so by sending them thank you messages, highlighting them in a Discussions post, or even sending them little gifts.
• 📊 Analyze your data and determine trending topics: Use Discussions insights to see what is most popular in your categories and track 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.
• 📖 Create content to generate engagement and enhance your community knowledge base, such as monthly check-ins, AMAs (Ask Me Anything), product update announcements, or blog posts written by subject matter experts.

📚 Further reading

▶️ Launching and managing your own GitHub Discussions community

• 💬 Discussions post: 4 ways your discussions categories can be better optimized
• 🌐 Blog post: How five open source communities are using GitHub Discussions
• 🌐 Blog post: 7 unique software collaboration features in GitHub Discussions
• 🌐 Blog post: Metrics for issues, pull requests, and discussions

📥 Resources to share with your community

• 💬 Discussions post: GitHub Community Programs
• 📣 GitHub Community Discussions Announcements: new features, events, beta programs, surveys, and more!
• 📚GitHub community Discussions Discover category: Blogs, articles, best practices, and tips & tricks from GitHub employees and users.

✅ Community checklist

💻 Setup + configuration

• [ ] Enable GitHub Discussions (on your repo // on your org)
• [ ] Grant helpful community members moderator or maintainer permissions
• [ ] Create categories
• [ ] Leverage Discussions category forms

💬 Community management + moderation

• [ ] Reply to posts in assigned categories
• [ ] Mark comments as answers
• [ ] Manage spam
• [ ] Lock/unlock Discussions
• [ ] Edit/delete comments
• [ ] Recategorise posts
• [ ] Pin discussions
• [ ] Create + add labels to discussions

🏆 Engagement & content creation

• [ ] Welcome new community members
• [ ] Recognise top contributors
• [ ] Analyze data for Discussions
• [ ] Create content