Merge branch 'main' into dependabot/pip/mkdocs-material-imaging--9.5.32

hacs · Aug 22, 2024 · a1ceac8 · a1ceac8
2 parents e9adc43 + 76ecf64
commit a1ceac8
Show file tree

Hide file tree

Showing 2 changed files with 44 additions and 43 deletions.
diff --git a/source/docs/help/index.md b/source/docs/help/index.md
@@ -5,20 +5,22 @@ description: "Help"
 
 ## Browse the documentation
 
-Learn more using the [documentation on this site](/index.md).
+Read the docs on the [using HACS](/docs/use/index.md), on [publishing your own custom element to HACS](/docs/publish/index.md), or on [developing HACS](/docs/contribute/index.md).
+
+## FAQ
+
+Maybe your question has already been answered in the [Frequently Asked Questions](/docs/faq/index.md).
 
 ## Stay up to date
 
 Find out what's new with this project over at [GitHub](https://github.com/hacs).
 
-## Want to submit a Bug?
+## Want to submit a bug?
 
-[Before you do make sure you first have a look here.](/docs/help/issues.md)
+If you're having an issue with a custom element, [report an issue for that repository](/docs/use/repositories/dashboard.md/#reporting-an-issue-with-a-repository).
 
-## Discord
+Experiencing an issue with HACS itself? [Create an issue for HACS](/docs/help/issues.md).
 
-For questions, you can join the [discord server](https://discord.gg/apgchf8), issues do still belong on GitHub.
-
-## FAQ
+## Discord
 
-[Frequently Asked Questions](/docs/faq/index.md)
+For questions, join the [discord server](https://discord.gg/apgchf8) to get help from the community.
diff --git a/source/docs/help/issues.md b/source/docs/help/issues.md
@@ -4,61 +4,45 @@ title: Issues
 description: "Got issues?"
 ---
 
-**[First lets start out by stating that _ALL_ issues should be reported here](https://github.com/hacs/integration/issues)**
+This page shows you how to report an issue for HACS.
 
-# What should be in the issue?
+# Reporting an issue
 
-When you create an issue in the repository for HACS, you start by selecting a template.
+If you're having an issue with a custom element, [report an issue for that repository](/docs/use/repositories/dashboard.md/#reporting-an-issue-with-a-repository).
 
-All templates have a defined structure and it is **expected** that you follow it.
+To report an issue with HACS, **[use one of the issue templates](https://github.com/hacs/integration/issues)**.
 
-_Issues that are missing required information can (will) be closed._
 
-## Flag
+- All templates have a defined structure. Follow the structure and provide the requested details.
+_Issues missing required information will be closed._
 
-This should **only** be used, when there is grounds for removing (blacklisting) a repository in HACS.
+## What should be in the issue
 
-When you are flagging a repository you need to supply at least these:
-
-- A good description for why.
-- The name of the repository.
-- Proof that you have tried to contact the owner of that repository (link to issue)
-
-_If you are flagging it because you don't like it, have issues with it, or it's not working, you should report that to the repository and not here._
-
-## Issues
-
-You use this when you have issues with HACS.
-
-[To enable debug logs for HACS (required when adding an issue) have a look here](/docs/use/troubleshooting/logs.md).
-
-Logs are **more** then _just_ errors, with debug logging it gives the person investigating the issue a full picture of what happened.
-
-
-**What an issue should contain depends on the type, but at least:**
+The content of the issue depends on the type of issue. At least, include the following information:
 
 - A GOOD description of the issue.
+  - Check out some real-world examples of [good](#examples-of-good-issues) and [bad](#examples-of-bad-issues) issue descriptions.
 - Debug logs.
+    - To enable debug logs for HACS, follow [the steps on enabling debug logs](/docs/use/troubleshooting/logs.md).
+    - Logs are **more** than _just_ errors; debug logging provides a full picture of what happened.
 - Steps to reproduce the issue.
 - If the issue is in the UI, add screenshots.
 - [Diagnostics](/docs/use/troubleshooting/diagnostics.md)
 
-You can see examples of good/bad issues further down on this page.
-
 !!! warning
-    _Issues that are missing required information can (will) be closed._
+    _Issues that are missing required information will be closed._
 
 
 !!! tip
-    oh... and almost forgot... `latest` is **NOT** a version.
+    oh... and almost forgot... `latest` is **NOT** a version. Provide the actual version number.
 
 
-# Examples
+## Issue examples
 
-This is a collection of good/bad issues.
+This section provides a collection of good and some bad (unhelpful) issue descriptions.
 
 
-## Examples of bad issues
+### Examples of bad issues
 
 ```text
 
@@ -101,14 +85,29 @@ I checked and it exactly how its supposed to be
 even replaced the whole hacs folder with a fresh download
 ```
 
-## Examples of good issues
+### Examples of good issues
 
-_Good issues have too much text to extract it (some also have screenshots) but here is a few links:_
+_Good issues have too much text to extract it (some also have screenshots), but a few are linked below:_
 
 - [https://github.com/hacs/integration/issues/452](https://github.com/hacs/integration/issues/452)
 - [https://github.com/hacs/integration/issues/470](https://github.com/hacs/integration/issues/470)
 - [https://github.com/hacs/integration/issues/356](https://github.com/hacs/integration/issues/356)
 
+# Flagging a repository for removal
+
+This should **only** be used when there are grounds for removing (blacklisting) a repository in HACS.
+
+_If you don't like a repository, have issues with it, or it's not working, you should report that to the repository owner, not to HACS._
+
+When you are flagging a repository, provide at least the following information:
+
+- A reason why this repository should be removed.
+    - "It's not working" is not an accepted reason.
+    - "It's not working and it has not been maintained for an extended period of time" could be a reason.
+- The name of the repository.
+- Proof that you have tried to contact the owner of that repository. 
+    - Provide a link to the issue you created in their GitHub repository.
+
 # Last words
 
-The more time/words/examples you put in your issue, the faster someone can see/understand what you mean.
+The more time/words/examples you put into your issue, the better the chance someone else can understand what your issue is. You are more likely to get help.