Merge branch 'main' of https://github.com/Virtual-Coffee/VC-Community-Docs into docs/add-pairing-challenge

Author: adiati98

docs/vc-discussion-boards.md

@@ -1,115 +1,102 @@
-# How to Use Discussions Boards
+# How to Use Github Discussions
 
 ## Table of Contents
 
-- [Why did we choose to use discussion boards?](#why-did-we-choose-to-use-discussion-boards)
-- [How to find a discussion?](#how-to-find-a-discussion)
-- [How to make a new discussion](#how-to-make-a-new-discussion)
-- [Question-type discussions](#question-type-discussions)
-- [When can I start a discussion?](#when-can-i-start-a-discussion)
-- [Who can start a discussion?](#who-can-start-a-discussion)
-- [What types of things made good discussion board topics?](#what-types-of-things-made-good-discussion-board-topics)
-- [Upvoting](#upvoting)
-- [What type of things won't be in discussion boards?](#what-type-of-things-wont-be-in-discussion-boards)
-- [How are discussions resolved?](#how-are-discussions-resolved)
-- [Recommendations for GitHub notification settings](#recommendations-for-github-notification-settings)
-- [In-App notifications](#in-app-notifications)
-- [Email notifications](#email-notifications)
-- [Feedback](#feedback)
+1. [Introduction](#introduction)
+2. [Why Github Discussions?](#why-github-discussions)
+3. [Finding and Creating Discussions](#finding-and-creating-discussions)
+4. [Best Practices](#best-practices)
+5. [Types of Discussions](#types-of-discussions)
+6. [Discussion Resolution](#discussion-resolution)
+7. [Notification Settings](#notification-settings)
+8. [Feedback](#feedback)
 
-Hey, welcome to being a member of the Virtual Coffee contributors community! As part of this community, you have access to [**Discussion Boards**](https://github.com/Virtual-Coffee/VC-Community-Docs/discussions); message boards here on GitHub where the majority of our communications take place. To help you get the most out of discussion boards we wanted to create a short guide.
+## Introduction
 
-## Why did we choose to use discussion boards?
+Welcome to the Virtual Coffee contributors community! This guide will help you navigate our [**Github Discussions**](https://github.com/Virtual-Coffee/VC-Community-Docs/discussions), the primary platform for our community communications.
 
-The Virtual Coffee maintainers spent quite a bit of time trying to decide the best possible way for all contributors to have discussions. It was important to us that the medium be:
+## Why Github Discussions?
 
-- Relatively straightforward to get into
-- Accessible for our contributors
-- Permanent so we could always reference earlier conversations
-- Flexible enough to work with the various types of communications a volunteer group like this need (ad hoc, q&a, open discussions, etc)
+We chose GitHub Discussions because they are:
 
-Seeing as we are already using GitHub for hosting our documentation and coordinating action items through issues, having conversations happen in discussions felt like the natural choice.
+- User-friendly
+- Accessible
+- Permanent for referencing past conversations
+- Flexible for various communication needs
 
-## How to find a discussion?
+## Finding and Creating Discussions
 
-- First, navigate to the [Discussions](https://github.com/Virtual-Coffee/VC-Community-Docs/discussions) section of the repo.
-- Pinned discussions at the top are we where we keep important discussions that we always want to be able to find quickly.
-- Discussions are organized by category and can be search and filtered by them, as well as recency.
+### How to Find a Discussion
 
-## How to make a new discussion
+1. Navigate to the [Discussions](https://github.com/Virtual-Coffee/VC-Community-Docs/discussions) tab.
+2. Use pinned discussions for quick access to important topics.
+3. Browse by category or use the search function.
 
-- Creating a new discussion is as simple clicking the [New Discussion](https://github.com/Virtual-Coffee/VC-Community-Docs/discussions/new) button, and choosing an appropriate category and title.
-- If you could see your discussion going into multiple categories, pick whichever you'd think is the most relevant (or what another person might look for to find it)
-- It may not always be relevant, but it is highly suggested to put as much context and framing into your original discussion post as necessary. Providing folks with enough info to assist you, or answer your question is preferred.
-- Remember that we're all volunteers here, and all efforts are people trying to make time from their other responsibilities. Sometimes, someone you've tagged in a discussion may not respond right away. If the information needed is time sensitive and a deadline is approaching, message a maintainer.
+### How to Create a New Discussion
 
-### Question-type discussions
+1. Click the [New Discussion](https://github.com/Virtual-Coffee/VC-Community-Docs/discussions/new) button.
+2. Choose an appropriate category and title.
+3. Provide context in your initial post.
+4. For questions, use the "Question" format to mark accepted answers.
 
-Discussion boards have direct support for question style discussions in which you can "accept" a response that someone provides. If you're opening a question discussion though, it's important to accept the right answer once it's provided. This lets other people know they no longer have to provide responses, and the discussion itself now becomes a resource they can use to find the right information.
+## Best Practices
 
-## When can I start a discussion?
+- Check existing discussions and issues before creating a new one.
+- Provide sufficient context in your posts.
+- Be patient with responses, as we're all volunteers.
+- For time-sensitive matters, contact a maintainer directly.
 
-You can start a discussion at any time, we only ask that you check the current discussions and open issues first to make sure that your particular topic hasn't already been addressed.
+## Types of Discussions
 
-## Who can start a discussion?
+### Good Discussion Topics
 
-Any Virtual Coffee contributor can start a discussion, however a maintainer may move/edit/remove said discussion if:
-
-- It's a duplicate of an existing discussion or issue
-- It's better addressed as an Issue
-- It breaks the [Virtual Coffee Code of Conduct](https://virtualcoffee.io/code-of-conduct/)
-
-## What types of things made good discussion board topics?
-
-- Ideas for new events, topics, projects that the community could be engaged in
-- Suggestions for changes in documents, processes, or actions
-- Asking for feedback on a concept or activity Before submitting it for official review/PR
-- Quick Q&A style questions where a contributor wants a specific answer on a VC-related topic
+- New event or project ideas
+- Suggestions for changes
+- Feedback requests
+- Q&A
 - Polls
 
-### Upvoting
+### What Doesn't Belong in Discussions
 
-Discussions support an upvote/downvote feature, both for discussions themselves and for individual responses, which can be a useful way of determining support for an idea, project, or direction, and doing vote tallies.
+- Official action items (use Issues instead)
+- Official documentation (added by maintainers to the repository)
 
-## What type of things won't be in discussion boards?
+## Discussion Resolution
 
-- Official Action items - Once something becomes a Task to be Done and everyone is settled on the requirements, it will be submitted as an Issue in the repo and assigned to an individual(s). In a similar vein, feedback for submitted PRs will be done in those specific PR threads.
-- Official Documentation will always be added by maintainers to the repository docs. You won't be expected to search through discussions for any official guides/docs.
+Discussions can be resolved by:
 
-## How are discussions resolved?
+- Marking as "Answered"
+- Converting to an Issue for actionable tasks
+- Pinning for ongoing relevance
+- Closing if no longer relevant
 
-Anyone in the repository space has the ability to respond to discussion topics. Depending on the time line and nature of the discussions, members will discuss in the discussion thread and share ideas, feedback, and resources. Eventually, all discussions must come to an end. A discussion can be closed in the following ways:
+Maintainers may:
 
-- A concluded discussion is marked as `answered`
-- The discussion produces some sort of task/action/or project and the discussion is closed, with the relevant details going to an Issue.
-- The discussion ends but the conversation is still relevant/evergreen and so the discussion is pinned at the top of the discussion board.
-- Sometimes a discussion needs a simple answer or the initial discussion is no longer relevant to to other activity in which case the discussion is marked as `answered` with no additional follow up.
-- Maintainers may move a discussion to another category if we see a better fit you may have missed (maintainers will always inform the original poster when this happens)
-- Similarly, an issue may be converted to a discussion if it's revealed that the issue's path to resolution isn't fully defined
-- Discussion replies may be hidden if they fall under the following categories
-  - Spam
-  - Abuse
-  - Off-Topic
-  - Outdated
-  - Duplicate
-  - Resolved
+- Move discussions to more appropriate categories
+- Convert Issues to Discussions when needed
+- Hide inappropriate replies
 
-## Recommendations for GitHub notification settings
+## Notification Settings
 
-### In-App notifications
+### In-App Notifications
 
-When it comes to how folks choose to get notified, we absolutely believe you should stick to whatever systems you have in please that work for you. However, for those who may be new to working on projects on the GitHub interface, or looking for a good method to receive notifications without being overwhelmed, we recommend the following:
+1. Go to the `VC-Community-Docs` repository.
+2. Click the "Watch" button.
+3. Choose your notification level:
+   - Recommended: "Participating and Mentions"
+   - For more updates: "Custom" with "Discussions" selected
 
-- Navigate to the `VC-Community-Docs` repository. You should see the `watch` toggle on the top right of the screen
-- Clicking this will reveal a drop-down that allows you to select what types of events in this repo you want to be notified about
-- We do not recommend `All activity` as people frequently find this overwhelming and end up tuning out repo events entirely. Ignore is also not recommended.
-- `Participating and Mentions` is our general recommendation. You'll receive notifications about any issue or discussion you're tagged in, and subsequent messages in those spaces on.
-- We also recommend the `Custom` setting, selecting discussions if you want to stay more updated on the general goings on in the repo. (Releases, issues and pull requests will rarely be relevant to those not already tagged on them).
+### Email Notifications
 
-### Email notifications
+Customize your email preferences:
 
-GitHub allows you to customize your email notification settings on a per-organization basis as well. [**Settings** -> **Notifications**](https://github.com/settings/notifications) -> **Custom Routing** will give you all the orgs you participate in, and allow you to customize which email accounts (out of those associated with your GitHub profile) that notifications will go to
+1. Go to [GitHub Settings -> Notifications](https://github.com/settings/notifications)
+2. Under "Custom Routing," set up organization-specific email preferences
 
 ## Feedback
 
-If you have any questions after reading this, please do not hesitate to [post a new Question discussion topic](https://github.com/Virtual-Coffee/VC-Community-Docs/discussions/new), ask a Virtual Coffee Maintainer about it, or email us at [email protected].
+For questions or feedback about this guide, please:
+
+- [Post a new Question discussion](https://github.com/Virtual-Coffee/VC-Community-Docs/discussions/new)
+- Ask a Virtual Coffee Maintainer
+- Email us at [email protected]