Documentation issues

IMHO, the documentation for HA has ALWAYS been confusing, minimalistic, and poorly written. I’ve written technical docs as part of my job in the past, and been in IT for almost 40 years. Honestly, HA docs are some of the worst I’ve seen for clarity. Clearer examples, and more of them, would be a huge help. There needs to be a comprehensive, in depth “beginners guide” or tutorial to clearly go over the basics of how the system works, how to set it up, etc. (if there is, I’ve not found it).
But you struggle through and figure it out eventually…with lots of great help from the forums. To be honest, this is a free system, so we can’t expect professional quality docs. Honestly I think the devs have done a really great job of putting it all together.


I somewhat agree but it is MILES better than the system I came from . Over there, they expected the USERS to write the documentation! Of course, that had its impact on accuracy,

This is an open-source project.
People write SW for free in a spare time.
Users who need a clear docs and SW w/o bugs may try to buy a commercial solution covering their personal needs.
I guess everyone who shares same values should participate - testing SW, registering issues, discussing implementation, proposing changes to the code & docs.


Users who don’t contribute code can contribute to the docs.

1 Like

But the developers know better the details of using the product…

But they don’t know to what level every user needs to be explained. That’s where the community comes to help. The problem is that most users figure it out and then don’t contribute what they learned that was different or needed a better explanation. A good amount do contribute and that is how the docs do better as a whole.


I find there are excellent descriptions of the options available, their default values, the value type they expect and enough examples to get me up and running on any YAML configured integration. You just have to know what to look for, e.g.

The default blurb for the UI configured integrations is less than ideal. I guess the UI is supposed to be self explanatory.

That last point could do with a similar table to the YAML integration options documentation explaining what exactly is required at each step.

1 Like

So pleased to find you volunteering. Welcome aboard.

When I first used HA around 2016 I read the install docs and then went through the integrations one by one. I read a lot about concepts that were unfamiliar, like mqtt. I then went through the docs page by page and read them. Some in detail, some just to skim. I then read a lot on the forum.

Seems people are lazy these days and just want it all done for them. Not referring to you, but also generalising.

Anyway as I say, good to have someone of your skills on board.


Since the move to UI, there is basically no documentation on the settings of an integration and there is no online help (besides the title).

Especially shitty when you try to help someone here and you have no clue on what to configure unless you install the integration yourself :wink:


I believe that is because the Integration developers are used to using files, especially when the UI was being developed and lacked features.

Well said.