Merge pull request #2 from MicrosoftCloudEssentials-LearningHub/docs

brown9804 · web-flow · commit 235f7dab52c4 · 2026-03-04T13:49:54.000-06:00
docs formatted
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,7 +1,7 @@
-## This repository is for GitHub Discussions
+# This repository is for GitHub Discussions
 
 If you intended to start a conversation (question, idea, proposal), please open a Discussion instead:
 
 - https://github.com/MicrosoftCloudEssentials-LearningHub/org-discussions/discussions
 
-If you truly need to change something in this repository (docs/templates), describe the change and why.
+If you truly need to change something in this repository (docs/templates), describe the change and why.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -11,9 +11,15 @@ See [docs/categories.md](docs/categories.md) for the intended use of each catego
 General guidance:
 
 - Use **Q&A** for questions that should end with an accepted answer.
+- Use **Support / Troubleshooting** for multi-step debugging or ongoing issues.
 - Use **Ideas** for product / process improvement suggestions.
-- Use **RFC** for larger proposals that need review.
-- Use **Show and tell** to share something you built or learned.
+- Use **Show and tell** to share something you built using the materials here (or related content).
+- Use **Events** for meetups, livestreams, and community events.
+- Use **Polls** to vote on topics and priorities.
+
+Optional (add later):
+
+- Use **RFC** for larger proposals that need review and a clear decision.
 
 ## How to write a great discussion
 
diff --git a/README.md b/README.md
@@ -1,4 +1,13 @@
-# org-discussions-public
+#  Repository that hosts the discussions (Public)
+
+Costa Rica
+
+[![GitHub](https://img.shields.io/badge/--181717?logo=github&logoColor=ffffff)](https://github.com/)
+[brown9804](https://github.com/brown9804)
+
+Last updated: 2026-03-04
+
+----------
 
 This repository is the **home for public GitHub Discussions** for the organization.
 
@@ -10,23 +19,25 @@ Use it to:
 
 ## Start here
 
-- **Want to ask a question?** Create a Discussion in **Q&A** and include:
+- **Want to ask a question?** Create a Discussion in [Q&A](https://github.com/orgs/MicrosoftCloudEssentials-LearningHub/discussions/categories/q-a) and include:
 	- What you expected vs what happened
 	- Repro steps (or a minimal example)
 	- Versions / environment details
-- **Have an idea?** Post in **Ideas** with the problem, proposed solution, and trade-offs.
-- **Need to report a security issue?** Do **not** post it publicly — see [SECURITY.md](SECURITY.md).
+- **Have an idea?** Post in [Ideas](https://github.com/orgs/MicrosoftCloudEssentials-LearningHub/discussions/categories/ideas) with the problem, proposed solution, and trade-offs.
+- **Need to report a security issue?** Do **not** post it publicly. Please see [SECURITY.md](SECURITY.md).
 
-## Categories (suggested)
+## Categories
 
-Create categories that match how people actually show up. A simple default set:
-- **Announcements** (maintainers only)
-- **Q&A** (questions with accepted answers)
-- **Ideas** (feature requests / improvements)
-- **Show and tell** (demos, write-ups, cool things you built)
-- **RFC** (bigger proposals that need review)
+> The Organization Discussions are organized into a few sections (Community / Product / Support)
 
-More detail (including “what goes where”) lives in [docs/categories.md](docs/categories.md).
+The canonical “what goes where” guide lives in [docs/categories.md](docs/categories.md).
+
+Quick pointers:
+- [Q&A](https://github.com/orgs/MicrosoftCloudEssentials-LearningHub/discussions/categories/q-a): clear questions with an accepted answer
+- [Support / Troubleshooting](https://github.com/orgs/MicrosoftCloudEssentials-LearningHub/discussions/categories/support-troubleshooting): longer debugging threads
+- [Ideas](https://github.com/orgs/MicrosoftCloudEssentials-LearningHub/discussions/categories/ideas): proposals and improvements
+- [Show and tell](https://github.com/orgs/MicrosoftCloudEssentials-LearningHub/discussions/categories/show-and-tell): what you built (demos/integrations)
+- [Events](https://github.com/orgs/MicrosoftCloudEssentials-LearningHub/discussions/categories/events): meetups/livestreams/webinars
 
 ## How we keep discussions useful
 
@@ -35,8 +46,14 @@ More detail (including “what goes where”) lives in [docs/categories.md](docs
 - **Use clear titles** (good: “CLI auth fails with 401 on Windows”, bad: “Help!!!”)
 - **Close the loop** when solved (summarize the fix and mark the answer if applicable)
 
-## Community & conduct
-
-By participating, you agree to follow our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
-
-If you’re not sure where to ask something, see [SUPPORT.md](SUPPORT.md).
+> [!IMPORTANT]
+> Community & Conduct:
+> - By participating, you agree to follow our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+> - If you’re not sure where to ask something, see [SUPPORT.md](SUPPORT.md).
+
+<!-- START BADGE -->
+<div align="center">
+  <img src="https://img.shields.io/badge/Total%20views-1337-limegreen" alt="Total views">
+  <p>Refresh Date: 2026-03-04</p>
+</div>
+<!-- END BADGE -->
diff --git a/docs/categories.md b/docs/categories.md
@@ -1,38 +1,26 @@
 # Discussion categories
 
-This page describes a suggested category setup for an organization Discussions hub.
+Costa Rica
 
-## Announcements
+[![GitHub](https://img.shields.io/badge/--181717?logo=github&logoColor=ffffff)](https://github.com/)
+[brown9804](https://github.com/brown9804)
 
-- **Purpose**: official updates from maintainers
-- **Examples**: releases, policy changes, scheduled maintenance, roadmap milestones
-- **Posting**: keep this restricted (maintainers/moderators)
+Last updated: 2026-03-04
 
-## Q&A
+----------
 
-- **Purpose**: questions with a concrete answer
-- **Best practices**: mark accepted answers; summarize the resolution at the end
+> This page describes the category setup for this organization’s GitHub Discussions hub.
 
-## Ideas
+| Section | Categories (type) | When to use it | Examples / best practices |
+|---|---|---|---|
+| Community | - **General** (Discussion)<br>- **Show and tell** (Discussion)<br>- **Polls** (Poll)<br>- **Events** (Discussion) | - **General**: anything community/meta that doesn’t fit elsewhere<br>- **Show and tell**: demos, write-ups, integrations, things you built<br>- **Polls**: quick votes to guide priorities (“next livestream topic?”, “next feature?”)<br>- **Events**: meetups/livestreams/webinars and follow-ups | - **General** titles: “How should we organize learning paths?”, “Introduce yourself + what you’re building”<br>- **Show and tell**: include a link/screenshot + short “how it works” + what you used from the provided materials<br>- **Polls**: keep options mutually exclusive (3–6), set a close date, and comment with the decision afterward<br>- **Events**: include date/time + timezone, agenda/link, and ask for RSVP via 👍 or a comment |
+| Product | - **Announcements** (Announcement)<br>- **Ideas** (Discussion) | - **Announcements**: official updates from maintainers (releases, policy changes, roadmap milestones)<br>- **Ideas**: suggestions and improvement proposals | - **Announcements**: start with a 2–3 line TL;DR; link to docs/issues; pin major updates if needed<br>- **Ideas**: use a simple structure (problem → proposal → trade-offs); include success criteria so others can evaluate it |
+| Support | - **Q&A** (Q&A)<br>- **Support / Troubleshooting** (Q&A) | - **Q&A**: questions that should end with a clear accepted answer (how-to, “what’s the right way?”)<br>- **Support / Troubleshooting**: longer back-and-forth debugging threads and ongoing issues | - **Q&A**: ask one clear question, share what you tried, and mark an accepted answer when solved (plus a short resolution summary)<br>- **Troubleshooting**: include expected vs actual, repro steps, environment/versions, and logs (redact secrets); summarize the root cause/fix at the end |
 
-- **Purpose**: suggestions, feature requests, process improvements
-- **Template**: problem → proposal → alternatives → trade-offs → success criteria
 
-## Show and tell
-
-- **Purpose**: share demos, write-ups, integrations, or lessons learned
-- **Note**: link to source or screenshots when possible
-
-## RFC
-
-- **Purpose**: bigger changes needing review and decision
-- **Template**: context → goals/non-goals → proposal → risks → rollout plan
-
-## Optional categories
-
-Add these only if you see sustained demand:
-
-- **Support / Troubleshooting** (if Q&A becomes too broad)
-- **Jobs** (if the community expects it)
-- **Events** (meetups, livestreams)
-- **Off topic** (only if you can moderate it)
+<!-- START BADGE -->
+<div align="center">
+  <img src="https://img.shields.io/badge/Total%20views-1337-limegreen" alt="Total views">
+  <p>Refresh Date: 2026-03-04</p>
+</div>
+<!-- END BADGE -->
diff --git a/docs/moderation.md b/docs/moderation.md
@@ -1,6 +1,15 @@
 # Moderation guide
 
-This is a lightweight playbook for keeping Discussions welcoming and high-signal.
+Costa Rica
+
+[![GitHub](https://img.shields.io/badge/--181717?logo=github&logoColor=ffffff)](https://github.com/)
+[brown9804](https://github.com/brown9804)
+
+Last updated: 2026-03-04
+
+----------
+
+> This is a lightweight playbook for keeping Discussions welcoming and high-signal.
 
 ## When to intervene
 
@@ -27,3 +36,10 @@ This is a lightweight playbook for keeping Discussions welcoming and high-signal
 
 - For security, redirect to [SECURITY.md](../SECURITY.md)
 - For conduct, redirect to [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)
+
+<!-- START BADGE -->
+<div align="center">
+  <img src="https://img.shields.io/badge/Total%20views-1337-limegreen" alt="Total views">
+  <p>Refresh Date: 2026-03-04</p>
+</div>
+<!-- END BADGE -->
diff --git a/docs/welcome-draft.md b/docs/welcome-draft.md
@@ -1,11 +1,26 @@
 # Welcome to the organization Discussions
 
-If you’re new here, start with the **Q&A** category for questions or **Ideas** for proposals.
+Costa Rica
 
-A few tips:
+[![GitHub](https://img.shields.io/badge/--181717?logo=github&logoColor=ffffff)](https://github.com/)
+[brown9804](https://github.com/brown9804)
 
-- Search before posting
-- Include enough context for others to reproduce/understand
-- Be kind; assume positive intent
+Last updated: 2026-03-04
 
-See the repository README for the full guide.
+----------
+
+- If you’re new here, start with [Q&A](https://github.com/orgs/MicrosoftCloudEssentials-LearningHub/discussions/categories/q-a) for questions or [Ideas](https://github.com/orgs/MicrosoftCloudEssentials-LearningHub/discussions/categories/ideas) for proposals.
+- If you’re debugging an issue that needs back-and-forth, use [Support / Troubleshooting](https://github.com/orgs/MicrosoftCloudEssentials-LearningHub/discussions/categories/support-troubleshooting).
+
+> [!TIP]
+> - Search before posting
+> - Include enough context for others to reproduce/understand
+> - Be kind; assume positive intent
+
+See [docs/categories.md](categories.md) for what goes where.
+<!-- START BADGE -->
+<div align="center">
+  <img src="https://img.shields.io/badge/Total%20views-1337-limegreen" alt="Total views">
+  <p>Refresh Date: 2026-03-04</p>
+</div>
+<!-- END BADGE -->
