Beginner friendly documentation

Hey all, I’m also totally new to HA and found the docs super hard to understand (even as a programmer). There’s a bit of a chicken-and-egg problem, which is that once you know about HA, it’s hard to write from a beginner’s perspective.

I hope this can be the start of bridging that gap. I put together a “mad libs” style outline of the docs I wish I had, take a look.

Comments are open, please feel free to copy/paste/remix freely. I can also convert this to markdown and submit this as a PR, though as you’ll see it’s very incomplete.

1 Like

Excerpts from your document:

Home Assistant calls the smart devices in your home Devices. An example would be a Hue lightbulb, an automated garage door opener, or a motion sensor.

Instead of automating devices, people in Home Assistant usually talk about editing entities. An entity represents some function of a device, like a single sensor or a single switch.

Two definitions, each defining a different concept, yet both use the same example: a sensor is a device and an entity.

Shimmer, it’s a floor wax and a dessert topping. :wink:

You didn’t make a mistake; you identified one of the aspects of Home Assistant’s evolving terminology.

In the beginning, there were only entities. A light bulb is a physical “thing” and is modeled as an entity (whose domain is light). If you have a physical “thing” that reports several properties like temperature, humidity, and light level, it is modeled as three separate entities (whose domain is sensor). However, there’s nothing to refer to the “thing” itself. As a result, there’s no means of showing the three sensor entities belong to a single physical “thing”.

The concept of devices was introduced as a means of identifying a “thing” and all the entities that are part of it. You have a multi-sensor device with three sensor entities reporting temperature, humidity, and light level. The same concept also paved the way for device automations.

For example, here’s an ecobee switch+ device with several entities. I can easily create device automations for it from its Device view:

If I look at the Philips Hue bridge device, it shows no entities.
Screenshot from 2020-09-17 00-07-30

Each Philips Hue light bulb is shown as a separate device. If you examine the device, it shows it has one entity, a light.
Screenshot from 2020-09-17 00-12-42

So in this example, a Philips Hue light bulb is both a device and an entity.


  • A device represents a physical thing.
  • A device may have zero or more entities.
  • An entity is typically a property of a physical thing but can also represent the thing itself.

That was a GREAT explanation. I think even I understand it now. Thank you!

But you sent me down a rabbit hole of SNL sketches on YouTube. Some great laughs, but there’s a half-hour of my life I’ll never get back!

1 Like

Thank you for reading @123! I updated the doc based on your explanation, hopefully it’s clearer.

Would love feedback from anyone else on the other missing pieces!

Your document’s definition of a Zone isn’t quite right. The definition of a zone can be found here. It’s a geographic area, typically used by a device_tracker (i.e. trigger an automation when you are detected to be approaching your home).

What your document describes (“rooms in a house”) is an Area. Currently, the concept of Area is underutilized and simply represents where a device is located.

Your definitions in the category Home Assistant Software are incorrect. Take a loot at the excellent overview that Taras created for the different install methods.

Supervisor is not only there to keep it all up-to-date, it’s also responsible for handling add-ons, backup and restore etc. You can find more details here.

Updated! Thanks @123.

This is exactly what I was hoping for. I think writing wrong documentation and waiting for it to get corrected is actually a decent way of getting documentation done :slight_smile:

@Burningstone thanks for the correction! I’ve updated it, is that better?

For others who might read this, I’ve highlighted the terms that seem important but weren’t clear to me from the glossary–suggestions very welcome.

@microfx @stevemann @nickrout @petro you might be interested in seeing this “HA core concepts” documentation. I would love your help writing/correcting it.

It’s better but I don’t think it’s a good idea to have links to forum posts or developer docs in the official documentation. Either a link to a separate doc page (non-dev doc page) or explain it on the same page.

Great point @Burningstone, I removed the link for now since I don’t see Supervisor mentioned in the non-dev docs.

Is supervisor something most HA users are supposed to know about, or just a dev thing? If it’s for everyone we should document it, but if it’s really just an implementation thing for developers, maybe it shouldn’t be called “Supervisor” in the UI… just my 2 cents.

I’ve also made this doc publicly editable so anyone can write changes.

I was told that Supervisor is destined to be deleted. Another good reason to be careful with links.

Where did you hear that? The Supervisor is a critical piece of Home Assistant and is actually being expanded upon, not destined to be deleted.


The supervisor will never go away, its integral to the main installation method.

That would be a quick leave from the party

1 Like


They refer to different things.

Home Assistant Supervised was targeted for deprecation but the plan was canceled. Home Assistant Supervised on Debian is an officially approved installation method (ADR-0014 Home Assistant Supervised).

Supervisor was recently enhanced (Supervisor joins the party).


You are confusing things. The Deprecation was only for any non-debian generic linux OS. Supervisor is also used in Home Assistant OS, which is the recommended install method by the devs.

Your Add-ons section is really describing Integrations.
When users think of all of those things, they should be looking here:

Add-ons are services for an installation of HA which includes the Supervisor (which is a service of its own). In such an install, HA is running in a docker container. Add-ons are other docker containers. The Supervisor is yet another container which manages all of this, and offers the add-on store, manages updates to all the parts, and provides snapshot functionality to back all of this up. Add-on containers may provide something simple, like a samba server, or ftp server. Or they may provide something more elaborate like a Plex server or VSC editor. They may have integrations associated with them, but they are not integrations themselves.

1 Like

Thank you @cogneato very helpful.

I’ve updated it with a note that says “not to be confused with add-ons” … is there a good link to the explanation you gave I can include? It seems too advanced for a beginner welcome tutorial.