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 the Microsoft Style Guide.

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.
• The case of brand names, services, protocols, integrations and platforms must match its respective counterpart. 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, 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.

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

Glossary & terminology tooltips

The documentation should be written in a way that is understandable for everyone. To help with that, we have a glossary of terms that are used across Home Assistant, including our documentation.

If you use a term that is not in the glossary, feel free to add; or improve the definition of an existing term.

Additionally, we have a terminology tooltip available, that can be added and works everywhere in the documentation. This tooltip will show a definition of the term when the user hovers over it with a link for more information. It provides instant context to terminology an user might not be familiar with.

The syntax for adding terminology tooltips is:

{% term <term> [<text>] %}

The term referenced must, of course, be listed in our glossary, which is the source for the tooltips.

For example, if you write a text about automations, you could add a tooltip like this:

This is an example text about {% term automations %}, which is used
to demonstrate the use of tooltips, in this case, for the term
"automations" earlier in this sentence.

The <text> is optional and can be useful if you want to add a terminology tooltip to a piece of text that differs from the term itself. In the following example the automation term tooltip is added to the "automate everything" text:

Awesome, because this allowed me to {% term automation "automate everything" %}
in my home! I love it!

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.