developers.home-assistant/docs/documenting/standards.md

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

Broadly speaking documentation should be written following Microsoft's house style, which is detailed here.

• 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. E.g., "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.
• The case of brand names, services, protocols, integrations and platforms must match its respective counterpart. E.g., "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.
• All examples containing Jinja2 templates should be wrapped outside of the code markdown with the {% raw %} tag.

Integration and Platform Pages

• 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.

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).
  • For configuration variables that accept multiple types, separate the types with a comma (i.e. string, integer).

Example Configuration Variables Block

{% configuration %}
some_key:
  description: This is a description of what this key is for.
  required: false
  type: string
  default: Optional default value - leave out if there isn't one
{% endconfiguration %}

UI Variables

• For describing UI Variables the {% configuration_basic %} 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 inside that YAML.

YAML Style Guide

Renaming Pages

It can happen that an integration or platform is renamed, in this case the documentation needs to be updated as well. If you rename a page, add an entry to the _redirects file as shown below. Please consider to add details, like release number or old integration/platform name, to the page in a note.

---
...
/getting-started/scripts /docs/scripts
---

Adding a redirect also applies if you move content around in the documentation.