I had meant to create this topic in the month of WTH, but it appears I got to it too late and new topics are closed there. I only have myself to blame for that
To me, the most important feature request is not in functionality, but rather documentation standards. As a developer myself, I know that no one likes having to put aside extra time to create and maintain documentation for the software they’ve created. Furthermore, it can be a thankless task because documentation gets obsolete very quickly and the maintainer gets blamed for it.
Nonetheless, as powerful and feature packed as HA is, it suffers badly due to inadequate user documentation that is also not comprehensive. I point this out precisely because this makes it difficult to appreciate the hard work HA’s contributors put into the software and use it to it’s full potential and thus expand HA’s user base.
Before I decided to switch over to HA from Indigo, which I had been using for almost 10 years, I had read warnings from users to prepare for frustration in HA’s learning curve. That seemed silly because HA looked very user friendly on the surface.
The reality is, it has a huge learning curve and it’s a painful process for new users to understand how to get it to do anything beyond switching on a light. This is evidenced by the large volume of confounded users in the forums here. Seasoned users do not notice this because they are used to the HA ecosystem.
In my opinion, this problem could be drastically improved with more complete and comprehensive documentation. For instance, if I am a new user switching to HA from another platform, and right off the bat I need automations that depend on a device tracker, I may follow the easy steps of flashing Hassio onto an SD, fire it up and get instant gratification when I see Lovelace for the first time. I’ll be thrilled that I can just tap through the menus and see a wizard for creating an automation, and expect the user interface to walk me through the steps of triggering something when I arrive home. I see an option to trigger on ‘Geolocation’, but don’t know how that is set up.
Then search for device tracker in the docs, and find this page:
While none of the individual pieces of information on this page is inaccurate, the information is so sparse that a new user may up being more confused after seeing the page than if they hadn’t.
For instance, after the two sentence description, the very next thing is a configuration snippet for a netgear configuration, followed by some esoteric information about configuration parameters.
There are no links other than ‘home zone’ on the page to any other documentation that would explain the very large number of HA concepts that are a prerequisite before the information on this page is useful- so at a glance, as a new user I need to understand:
- What is a platform?
- What is configuration.yaml? May be obvious to someone who has done any customizations at all, but what about a new user who has only seen Lovelace?
- There is an example for netgear platform, what are all the integrated platforms, and do they all use the same parameters and behave the same way?
- What is a service, and how can I use the one described on this page?
- What is known_devices.yaml, and what purpose does it serve in HA? Also, why does one note describe current behavior with it, and another note say it is being phased out? Even more confusing is the large number of community posts that mention this file and troubleshooting it.
Finally, even if I understand all the above, what is a device tracker’s behavior in HA? If a device tracker’s status shows a particular named location or ‘stationary’ on a person’s banner icon, how do I know whether that means home or not home in HA?
I’m just using device_tracker as an example here, but that one was a particularly frustrating experience for me to learn more about it by reading other users’ struggles with it than from HA documentation of this core concept.
Given that making good documentation can be time consuming, especially if you want to provide a complete set of examples and recipes that work and are up to date, perhaps a more ‘wiki’ style of documentation could work? One where users in the community have the ability to easily submit amendments to the HA documentation for approval by a developer or moderator?