Move general style guide to its own page (#2647)

docs/documenting/general-style-guide.md

@@ -0,0 +1,34 @@
+---
+title: "General style guide"
+---
+
+Documentation should follow the [Microsoft Style Guide](https://learn.microsoft.com/style-guide/welcome/).
+
+A few of the most common cases picked up in reviews are listed below:
+
+- The language of the documentation should be American-English.
+- Don't put two spaces after a period.
+- Use a serial comma (also known as the Oxford comma) before the conjunction in a list of three or more items. For example, "Through the use of additional adapters, Home Assistant allows the use of Zigbee, Z-Wave, and other protocols".
+- There is no limit for the line length. You are allowed to write in a flowing text style. This will make it easier to use the GitHub online editor in the future.
+- Be objective and not gender favoring, polarizing, race related or religion inconsiderate. Contributions which do not follow this may be in breach of our [Code of Conduct](https://github.com/home-assistant/core/blob/master/CODE_OF_CONDUCT.md).
+- The case of brand names, services, protocols, integrations, and platforms must match their respective counterparts. For example, "Z-Wave" _not_ "Zwave", "Z-wave", "Z Wave", or "ZWave". Also, "Input Select" _not_ "input select" or "Input select".
+- Do not use ALL CAPITALS for emphasis - use _italics_ instead.
+- Use [sentence-style capitalization](https://learn.microsoft.com/en-us/style-guide/capitalization), also in headings.
+- Use **bold** to markup UI strings, for example:
+  - Under **Settings**, select the three dots menu. Then, select **Restart Home Assistant** > **Quick reload**.
+- Don't use "e.g.". Instead, use _for example_, _such as_, or _like_.
+- All examples containing Jinja2 templates should be wrapped _outside_ of the code markdown with the `{% raw %}` tag.
+
+## Tables
+
+- Avoid the use of tables. Use lists instead. If you cannot avoid a table, minimize the number of columns and keep the amount of text as short as possible:
+  - Tables that are too wide can be difficult to browse on handheld devices.
+  - Less content makes tables easier to read.
+- When limiting the amount of text is not possible, consider using other data structures for representing the information. For example, lists or `{% configuration_basic %}` can be used.
+
+## YAML and templates
+
+We have a separate styling guide for YAML and the use of Jinja2 templates
+inside that YAML.
+
+[YAML Style Guide](documenting/yaml-style-guide.md)

docs/documenting/integration-docs-examples.md

@@ -7,8 +7,9 @@ This page shows examples of the available documentation features (such as inline
 Use this template together with the following documentation:
 
 - The integration documentation template in the home-assistant.io repository under [/_integrations/_integration_docs_template.markdown](https://github.com/home-assistant/home-assistant.io/tree/current/source/_integrations/_integration_docs_template.markdown).
-- [Documentation standard](https://developers.home-assistant.io/docs/documenting/standards).
+- [Documentation standard](/docs/documenting/standards).
-- The documentation rules of the [Integration Quality Scale](https://developers.home-assistant.io/docs/core/integration-quality-scale/).
+- [General style guide](/docs/documenting/general-style-guide).
+- The documentation rules of the [Integration Quality Scale](/docs/core/integration-quality-scale/).
 
 ## Inline text elements
 

docs/documenting/standards.md

@@ -4,24 +4,9 @@ title: "Standards"
 
 To ensure that the documentation for Home Assistant is consistent and easy to follow for both novice and expert users, we ask that you follow a very strict set of standards for developing the documentation.
 
-## General documentation
+## Style guide
 
-Broadly speaking, documentation should be written following the [Microsoft Style Guide](https://learn.microsoft.com/style-guide/welcome/).
+Documentation should follow the [Microsoft Style Guide](https://learn.microsoft.com/style-guide/welcome/). For more details, refer to the section [General style guide](documenting/general-style-guide.md) and the [YAML style guide](documenting/yaml-style-guide.md).
-
-A few of the most common cases picked up in reviews are listed below:
-
-- The language of the documentation should be American-English.
-- Don't put two spaces after a period.
-- Use a serial comma (also known as the Oxford comma) before the conjunction in a list of three or more items. For example, "Through the use of additional adapters, Home Assistant allows the use of Zigbee, Z-Wave, and other protocols".
-- There is no limit for the line length. You are allowed to write in a flowing text style. This will make it easier to use the GitHub online editor in the future.
-- Be objective and not gender favoring, polarizing, race related or religion inconsiderate. Contributions which do not follow this may be in breach of our [Code of Conduct](https://github.com/home-assistant/core/blob/master/CODE_OF_CONDUCT.md).
-- The case of brand names, services, protocols, integrations, and platforms must match their respective counterparts. For example, "Z-Wave" _not_ "Zwave", "Z-wave", "Z Wave", or "ZWave". Also, "Input Select" _not_ "input select" or "Input select".
-- Do not use ALL CAPITALS for emphasis - use _italics_ instead.
-- Use [sentence-style capitalization](https://learn.microsoft.com/en-us/style-guide/capitalization), also in headings.
-- Use **bold** to markup UI strings, for example:
-  - Under **Settings**, select the three dots menu. Then, select **Restart Home Assistant** > **Quick reload**.
-- Don't use "e.g.". Instead, use _for example_, _such as_, or _like_.
-- All examples containing Jinja2 templates should be wrapped _outside_ of the code markdown with the `{% raw %}` tag.
 
 ## Integration and platform pages
 
@@ -54,13 +39,6 @@ some_key:
 
 - For describing **UI Variables** the `{% configuration_basic %}` section can be used.
 
-### Tables
-
-- Avoid the use of tables. Use lists instead. If you cannot avoid a table, minimize the number of columns and keep the amount of text as short as possible:
-  - Tables that are too wide can be difficult to browse on handheld devices.
-  - Less content makes tables easier to read.
-- When limiting the amount of text is not possible, consider using other data structures for representing the information. For example, lists or `{% configuration_basic %}` can be used.
-
 ## YAML and templates
 
 We have a separate styling guide for YAML and the use of Jinja2 templates

sidebars.js

@@ -297,6 +297,7 @@ module.exports = {
       items: [
         "documenting",
         "documenting/standards",
+        "documenting/general-style-guide",
         "documenting/yaml-style-guide",
         "documenting/create-page",
         "documenting/integration-docs-examples",