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
Supervisor
Supervised
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: https://www.home-assistant.io/integrations
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.
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.
There are several other things in there that me wrinkle my nose, like this one:
Entities in Home Assistant are controlled by sending events.
Is the target audience end-users or developers?
End users I think–that’s the purpose of this thread IMO.
I’ve moved this to a PR, could definitely use your feedback/suggestions since I literally have no idea what I’m talking about and just made all this up based on a cursory doc read.
If it’s end-users, why are you describing how events control entities? From your personal experience as an end-user, how do you control an entity?
From tapping a card? Tbh I don’t really control entities because I haven’t gotten HA to connect to much yet, still trying to wrap my head around what this this is 
I’ll happily remove events, or at least demote if that’s what you’re suggesting! I was trying to go for parity with the current glossary but maybe that’s not a good goal.
In general I think deciding what’s in Userland and focusing UI and Docs only around that, and leaving Developerland docs and code separate is a great idea.
I don’t mean to sound rude but that explains some of the oddities in the document.
Whenever you get around to creating an automation to control an entity you will find that ‘tapping a card’ isn’t involved nor is ‘sending it an event’.
I commend you for your initiative but I suggest you spend more time learning Home Assistant before composing documentation. At least six months of comprehensive usage.
The word “Event” has a special meaning and represents a type of signaling in Home Assistant. It isn’t wrong to say that one can control things with events but the way a user like you or me actually does that (in an automation) is with a service call (such as light.turn_on).
Speaking about documentation I was struggling recently with getting ssh access to underlaing system. Of course most suggestions found on forum don’t work.
For example issuing login from ha cli ended up with asking me for login. Of course no combination of login/pass worked. based on what I’ve learned during last year it should work but it dosn’t.
I found following note in Debugging the Home Assistant Operating System
The note might be missleading. For example one might not know that connecting to ssh on port 22 (using ssh client like putty) in fact makes use of SSH addon. I collected this knowledge reading several posts but it wasn’t clear to me from beginning.
BTW prsonally I think that it’s wrong decision to make access to ssh on port 22 via addon, while access to OS is moved to port 22222.
Another case is wording itself. it suggest that user/password login command is asking for something what user will learn later in article. But as I understood login command will never work this way.
And there is another issue: in fact it works on clean install (it is on my testing Pi with HAOS 5.2). I suppose it stops working after installing ssh addon. Then why should one install ssh addon at all?
I cannot even think about fixing this part of manual because I have no enough knowledge about it. But I feel it so incomplete.
Why are you trying to access the OS? The first disclaimer on that document:
Those are the debug documents for developers of the HA OS. An end user does not need to do that. This is why port 22 is used for the addon.
several reasons:
TBH I don’t understand this ‘inventing the wheel’ thing. Why so ammount of things in HA is being done different way then found in other systems. Why so limited access to OS? Why trying to provide HA CLI which is so limited comparing to bash. Why to swap ssh ports… etc etc. maybe there is a document which describes reasons. But I really wondering why. However maybe it’s not a proper place to get answers for that. What should be more clear is what I wrote above: when login command is available and when not and why.
You can add authorized keys in the SSH addon to not use a password.
This is on purpose, end users aren’t supposed to be using this with HomeAssistantOS. See the disclaimer:
You’re not supposed to do that on homeassistantOS. If you want to do that you should move to supervised. This is why the documents for this assume you know what you’re doing.
No offense taken, that is exactly why the document has oddities 
No way boss, the documentation is bad and we gotta fix it!
Will you comment on the oddities in the PR so it ships with correct info? Or you could rewrite it how you think it should be, I won’t be offended–as long as the docs improve I’m happy.
