Every time Home Assistant changes the UI or moves a feature, all the existing docs, blog posts, and LLM chat answers go stale overnight.
Example: Long-Lived Access Token. Half the posts and tools still tell you to look at the bottom of your profile page, which was true six months ago. Now it’s tucked under the Security tab instead. When you’re trying to get something simple working… like connecting Node-RED or another API client… it turns into a guessing game. Sure, it’s my fault I missed it, but visually the advice sent me to the bottom of the page because that’s where it’s usually been. I’m burning hours chasing my tail due to cosmetic changes confusing the LLM. Home Assistant is a victim of its own success and is now far ahead of its documentation base. Need another example? “Action.” While it may sound good conceptually, it means several thousand YouTube videos are now out of date.
It’s super positive that HA is always moving forward, but we need a workaround. The YouTube developers need a workaround… for those of us relying on search or chat tools to get straight answers, constant UI reshuffles make it almost impossible.
One-line notices in the release notes or even a redirect in the UI (“tokens moved to Security tab”) might save a lot of chasing tails. Is there any plan or resource available to provide a straight, clean package or maybe a research tool that stays in sync with the current layout?
I’d be interested to hear if there are established ways deal with version drift. Specifically a better documentation path where settings live would really help everyone.
In someones wildest dreams maybe? Resource available… At Nabu they have way higher priorities and one of them better be true RBAC before they ever consider this as a priority. Sorry. Drift happens. As an LLM practitioner I’m used to it. It’s a fact of life. I was just espousing the fact they YOU SHOULD NOT TRUST any llm re: ha yaml coding because at BEST they will always be 8-idh months behind because training schedules etc.
YouTube be YouTubin you go try to tell a content creator who has a popular video that earns clicks to remove it. (won’t happen)
They have been getting better in release notes at least the ones on the main page. (as long as they get rid of that blasted backward whatever… Ugh. it’s freaking breaking changes! The entire damn industry uses the verbiage there is no need to change it… But I digress)
My only real problem is witb the constant bump to version… With no clue what fixes are actually in Version x.y.86. That unfortunately is a problem for EVERY single open source project. A d will continue to be although one nice side effects of having N LLM attached to GitHub is it now infers the comments for my checkins and it’s not bad… so maybe the docs will get better…
Until then it’s going to be incumbent upon all of us to keep reading the… Manual…
yes, it comes down to resources and priorities
yes, no one likes to update documentation
yes, a better job could be done (industry wide)
yes, videos/blogs constantly get outdated themselves, because change happens
one thing I think could be done, when doing doc updates, adding version info to documentation, indicating at what specific HA version the documentation was last confirmed against.
this may not help the videos/blogs, and screw ai, but it will at least help keep track of where the official documentation becomes stale.
There are tasks that must be completed when submitting changes. One of them is updating the documentation. This is easy for integrations with defined locations. Not so much for things that might be mentioned in multiple places and occasionally things are missed.
So the community is asked to help out. Please do at least provide feedback if you notice something wrong. Edits are also very easy to do. Become part of the solution and give back to this project.
