Skip to main content

General style guide

Documentation should follow 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 their respective counterparts. 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.

Tables​

  • Avoid the use of tables. Use lists instead. If you cannot avoid a table, 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