diff --git a/docs/documenting/general-style-guide.md b/docs/documenting/general-style-guide.md new file mode 100644 index 00000000..19460227 --- /dev/null +++ b/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) diff --git a/docs/documenting/integration-docs-examples.md b/docs/documenting/integration-docs-examples.md index 35970afc..e00442b2 100644 --- a/docs/documenting/integration-docs-examples.md +++ b/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). -- The documentation rules of the [Integration Quality Scale](https://developers.home-assistant.io/docs/core/integration-quality-scale/). +- [Documentation standard](/docs/documenting/standards). +- [General style guide](/docs/documenting/general-style-guide). +- The documentation rules of the [Integration Quality Scale](/docs/core/integration-quality-scale/). ## Inline text elements diff --git a/docs/documenting/standards.md b/docs/documenting/standards.md index 6862adee..ff41aa30 100644 --- a/docs/documenting/standards.md +++ b/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/). - -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. +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). ## 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 diff --git a/sidebars.js b/sidebars.js index abfc72e6..e59771f7 100644 --- a/sidebars.js +++ b/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",