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
ortrue
). - 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
).
- For configuration variables that accept multiple types, separate the types with a comma (i.e.
- 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
orapi_key: REPLACE_ME
.
- Use capital letters and
- Integration and platform names should be a link to their respective documentation pages.
Example configuration block
#
YAML and TemplatesWe have a separate styling guide for YAML and the use of Jinja2 templates inside that YAML.
#
Renaming PagesIt 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.
Adding a redirect also applies if you move content around in the documentation.