Improve platform/integration doc writing standards (#1101)

Co-authored-by: Franck Nijhof <git@frenck.dev>

docs/documenting/standards.md

@@ -19,18 +19,20 @@ Broadly speaking documentation should be written following Microsoft's house sty
 
 ## Integration and Platform Pages
 
-- The **Configuration Variables** section must use the `{% configuration %}` tag.
-- The **Configuration Variables** section is only used for YAML configuration.
-- For describing **UI Variables** the `{% configuration_basic %}` section can be used.
-- Configuration variables must document the requirement status (`false` or `true`).
-- Configuration variables must document the default value, if any.
-- Configuration variables must document the accepted value types (see [Configuration variables details](documenting/create-page.md#configuration)).
-  - For configuration variables that accept multiple types, separate the types with a comma (i.e. `string, integer`).
 - All examples should be formatted to be included in `configuration.yaml` unless explicitly stated.
   - Use capital letters and `_` to indicate that the value needs to be replaced. E.g., `api_key: YOUR_API_KEY` or `api_key: REPLACE_ME`.
 - Integration and platform names should be a link to their respective documentation pages.
 
-Example configuration block
+### Configuration Variables
+
+- The **Configuration Variables** section is only used for YAML configuration.
+- The **Configuration Variables** section must use the `{% configuration %}` tag.
+- Configuration variables must document the requirement status (`false` or `true`).
+- Configuration variables must document the default value, if any.
+- Configuration variables must document the accepted value types (see [Configuration variables details](documenting/create-page.md#configuration)).
+  - For configuration variables that accept multiple types, separate the types with a comma (i.e. `string, integer`).
+
+#### Example Configuration Variables Block
 
 ```yaml
 {% configuration %}
@@ -42,6 +44,17 @@ some_key:
 {% endconfiguration %}
 ```
 
+### UI Variables
+
+- For describing **UI Variables** the `{% configuration_base %}` section can be used.
+
+### Tables
+
+- Be succinct. Minimize the number of columns and keep the amount of text as short as possible:
+  - Too wide tables are 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