From a0e2666bc1c56c60e6ec47dc026ec7b8e6a2efae Mon Sep 17 00:00:00 2001 From: Teemu R Date: Thu, 6 Jan 2022 21:36:02 +0100 Subject: [PATCH] Improve platform/integration doc writing standards (#1101) Co-authored-by: Franck Nijhof --- docs/documenting/standards.md | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/docs/documenting/standards.md b/docs/documenting/standards.md index 89d89a2c..136283c8 100644 --- a/docs/documenting/standards.md +++ b/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