I’d like to see better documentation. Most of the instructions to do stuff seems really half baked. Or it’s written for somebody who already knows what they are doing. If I google a solution, I usually end up finding solutions from previous HA versions that don’t apply anymore. This goes for community integrations, too. There is no reason why the instructions for an integration on github should be telling me to put the resources in my lovelace.yaml.
Moved your suggestion into a separate topic, as suggested in the topic you originally replied on…
I kinda agree on this. However 3 things:
- It is kinda generic. The documentation counts around 2000 pages. Saying “Better documentation” is a bit broad.
- The documentation is actually something everybody can contribute to. If you see something weird, please be sure to hit the “edit” button that is listed on top of each page in the documentation.
- We can’t control Google
8 Likes
The issue with documentation is sometimes things are just hard. Some integrations, custom especially require some sort of knowledge going in. Not to say it cant be better but sometimes it just takes more research. Also, we rely on the developers who created the integration or feature to document it. And thats the least fun part 
I think an interesting piece here would be versioned documentation.
Having run HA for many of its 7 years, I personally find the most confusing part of the documentation being “what’s different”.
As a terrible example, years ago the way to handle grouping multiple lights was to create a group. Then light groups came about, but the groups documentation never updated to indicate that light group was a thing and better than just a group. I’ve looked at the group documentation 100 times since light group was introduced in .067, I never knew it existed until I happened upon it trying to remember syntax when building a new install on .110
In this case, “why the heck” isn’t there versioned documentation so specific call outs or massive improvements can be added without changing the previous documentation. It seems like this would add to clarity in documentation immensely.
3 Likes
Honestly, I personally truly believe that will make things worse in general. If one goes into versioned documentation, it has to be good overall in the first place. Or else one would end up with multiple incomplete versions (that are frozen/versioned forever).
1 Like
I do have a tendency to put the cart before the horse.
I get what you’re saying though. Documentation is hard. I’ve literally hired people in the past just to write it.
I wonder if there’s be a way to link “significant” release notes to documentation?
Another terrible example, I didn’t know the Denon component was a UI flow integration now.
Or now that I type that out, maybe a badge or indicator that something can be configured via the UI would make a lot of the documentation unnecessary for some folks?
Either way, I’m in the process of rebuilding an instance and reading a lot of docs. I have a lot of free time this weekend, glad I signed that CLA. 
1 Like
The base issue generally is that if someone has solved an issue that wasn’t well covered by the documentation, they usually don’t go back and make it clear for others. I know that’s at least the case for me if I think about it. Very often I’ve needed to dig down a little, but for some reason I didn’t even think about improving the documentation.
Now if that was a lot of work I think it is somewhat excusable, but often a few sentences would be enough.
I’m not sure how, but I think part of the issue could be solved by simply ‘selling’ improving the documentation better. At the least I think the barrier needs to be as low as a wiki page (but that’s already more or less the case).
I didn’t realize I could edit documentation. I’ll keep that in mind, thanks!
I understand that you guys can’t control Google or force people to update their github descriptions of custom addons. I think that comment was more of wishful thinking that someone was going to read it and say, “Hey maybe I should update my documentation!”
As an engineer, I’m constantly telling my guys they need to think like an engineer but communicate so a layman can understand. But don’t dumb it down too much because you we are supposed to be the smart ones in the room. It’s a delicate balance that engineers don’t pull off well. All of this is just a long winded way of saying I totally get the uphill battle of getting developers to document things clearly so us laymen can understand it.
3 Likes
Whenever I’ve looked at the documentation when I’m trying to understand what I need to do there is usually one or not enough examples - especially the automation and templates the functions you need to call etc.
As a newbie, I am constantly searching for how to go about something and one issue I face is OLD threads about how to achieve something which by now is deprecated or there are much easier ways to achieve. I would love the documentation to have more/better examples.
1 Like
I think one of the biggest issues with the docs is a lack of template examples. Every time I need to create a template I have to hunt through this forum for examples and try to piece something together. The examples in the docs are very limited
How about a note in the doc saying what version was current at the time it was written?
The real issue around this I think is that I’ll be halfway into implementing something based on a given doc for something only to find that since that doc was written other better simpler ways of achieving the same goal have come out later deprecating the need for the more complex way I was going about it. That doc though was written long before said newer way came out so it offers no clues as to this new methods existence. Maybe even just a related docs section at the bottom that accurately refers me to other commands?
Like the section on groups having a reference to light groups and so on.
3 Likes
I second the idea of having an “confirmed to work on version xx” tag.
The initial writer could define it. Also, if another user has used the doc in a more current version and was successful, he/she can confirm this new version to be working.
1 Like
Documentation is my main bugaboo - I’ve let my implementation stagnate and I’m coming back with fresh eyes to rebuild on a stable platform (I’m really sick of Raspberry Pis).
Is this documentation relevant #1:
Could we get something like Django where you select the appropriate HA version while viewing documentation? (Yes, they don’t have nearly as many versions, so maybe this is unwieldy here, but something like).
Is this documentation relevant #2:
Also, after catching up a little on the “Supported installation methods” from the blog post in May, having install tags [HA, Contained, Supervised, Core] on the documentation would be tremendous.
General critique on state of documentation
It strikes me as a fundamental problem that the main home-assistant.io page states “Perfect to run on a Raspberry Pi or a local server.” and then the /getting-started/ banner link drops the user right into installing on a Pi - the local server option being pretty tough to dig out.
To somewhat add to the confusion, the URLs and titles of the installation documentation offer little to help the user locate themselves.
“Install Home Assistant” - /getting-started/ (sometimes linked as [beginners] ‘getting started guide’)
“Installing Home Assistant” - /hassio/installation/
“Installation of Home Assistant” - /docs/installation/
What I’m trying to say is that it’s not that the documentation contains errors, but that the organization of information is haphazard.
Final remarks
I hope some of these critiques/ideas help form a more specific idea of ‘better documentation’. I’m going to try contribute where I can in improving documentation, though it seems to need a good framework revamp before we’ll see major benefits.
3 Likes
Maybe exhaustive documentation can be avoided if HA would be more explanatory for contexts in the front end? e.g. scenes. just an idea…
If you could give me some ideas on template examples, I can add a few to the help.
I know everybody can contribute to the documentation but one of the issues that should be easy to address is that a lot of information about new or changed features are written in the blog post of the release but never reaches main documentation.
Take areas as an example. When you want to understand or read about areas, you need find the blog posts describing it.
Solution:
Update documentation with the same info when writing the blog post 
Tags for each to show confirmed compatibily is what Kodi (formerly XBMC) does in their wiki.
Could maybe use tagging to indicate “Confimed working with HA core 0.95 to 0.114” and then keep a seperate section on a page if a procedure is very different from one version to another?
But this would probably be harder to implement when Home Assistant core does not currently utilize Semantic Versioning. This as as Semantic Versioning releases mean MAJOR.MINOR.PATCH and documentation usually only need major changes in each major version release.
Most integration components (and their dependencies) for Home Assistant I have used and seen however do use Semantic Versioning.
I’d have to have a hard think about some ideas. The main ones I can think of straight away would be:
- if entity state is equal to / greater than / less than X
- if entity state is equal to / greater than / less than some other entity / entity attribute
- if entity attribute is equal to / greater than / less than X
- if entity attribute is equal to / greater than / less than some other entity / entity attribute
- service- turn_on / off something if current time is before/after value / input_datetime else turn on/off
When I get a chance to log into my system I’ll try to find some more examples