Skip to main content

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.

Style guide​

Documentation should follow the documentation style guide and Microsoft Style Guide.

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. For example, api_key: YOUR_API_KEY or api_key: REPLACE_ME.
  • Integration and platform names should be a link to their respective documentation pages.

YAML and templates​

For YAML and the use of Jinja2 templates inside that YAML, follow the 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 shows a definition of the term when the user hovers over it with a link for more information. It provides instant context to terminology a 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!

Adding glossary entries​

To add an entry to the glossary, edit source/_data/glossary.yml.

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.