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

• The language of the documentation should be American-English.
• Don't put two spaces after a period and avoid the "Oxford comma".
• 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.
• 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

• 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_base %} 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).
  • 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 %}
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 %}

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.