I’m one of the rare people that go read the release notes as published, but it’s tedious because she betas clutter up the point release notes
That said, the change log that comes out on a monthly basis Changelog - ESPHome - Smart Home Made Simple is a pleasure to read. It’s just that the point releases don’t get this treatment (probably because they’re a lot).
And while the point releases usually mostly consist of fixes, currently especially the Esphome builder updates hide feature drops like support for headless remote build nodes (I have a machine that is bored that could take this role).
So yeah, this is a complaint about churn. We can’t keep up, and we will miss important stuff.
Actually, it reads like that was written by AI (the change log, not the post). AI can be pretty decent at doing the hard work of following all the “bumped” changes to figure out what really changed and why. It can also do a decent job of summarizing, but any summary loses resolution on what changed. But, how much detail is enough and how much is too much. I suspect that bar is different for different people. AI can create an Executive Summary, highlights section, and Gory Details for those that really want to know. Perhaps that would solve the problem for most people.
Personally I now read all the release notes after receiving a “why didn’t you read the release notes” remark … in the hope that I might recognise a brand or integration name that I recognise among the technical gobbledygook. Release notes just support my view that Home Assistant - and ESPHome even more so - is by engineers for engineers.
Your voice matters
Crucially, this process isn’t just for developers. Whether you’re an established user or just getting started, your voice matters. Your experience in your own home is the most valuable resource we have… and you don’t need to write a single line of code to help steer our direction.
That’s because one of our biggest priorities is making Open Home Foundation projects – Home Assistant, Music Assistant, and even ESPHome – more approachable for anyone. We’re reducing the barriers to entry, without removing any of the power established users expect. Or as Franck put it onstage: “We really want to lower the floor without lowering the ceiling”.
So there is some effort to make it better for all. I believe this will be hard to achieve.
Neel, I don’t know what your background is, but over the years I have seen that top management’s public statements rarely have any connection to the procedures actually followed by the business. The bigger the business, the greater the disconnect. Yes, i am old and cynical …
I also acknowledge that
Home Assistant is not a business - though it does have management and a structure.
Home Assistant is improving - its communications with users, its planning and standards, its user interface and documentation. ESPHome seems to be lagging behind.
Home Assistant covers so much, and is constantly growing - it’s an impossible moving target
Nabu Casa now employs some non-technical and professional documentation specialists.
However, Nabu Casa, Home Assistant project and ESPHome project are run by “developers” - who are effectively electrical or software engineers. That’s the Open Source model, and I am so thankful they’re not motivated by profit.
Like almost all people, they have the unspoken assumption that because they are “normal”, other people are like them - which in this case assumes similar levels of technical expertise and sometimes even understanding of the internals of Home Assistant & ESPHome. Fortunately it’s a while since I last saw a user told to “go read the source code”.
Alas I have found that in practice my voice does not matter. Most of the PRs I have submitted (including several to improve ESPHome documentation) have been closed as stale without any comment or indication that any of the developer class ever looked at them. Heck, just using github to submit a PR requires a developers level of detail and expertise - which is overwhelming to a new user. But I don’t want to hijack this thread by expounding further here.
Yes, there is effort and noticeable improvement … and it is a huge challenge with a long way still to go.
I have heard that the developers hang out on Discord. I remember when Tasmota moved to that. I didn’t like it and found it hard to use (but that was a decade ago).
I suspect that the developers have too much to do and not enough time to do it all, so they prioritize (generally when developers do that they write more code).
Perhaps go to Discord and see if there is interest in the changes you are suggesting. There also was someone posting here looking for feedback from non-developers. Perhaps they would help with the reviews.
I have used Discord and got answers … but I also don’t like it. Seems like instant messaging, suited for quick short answers rather than explanations or conversations … and didn’t appear to have any real history (so the same answers have to be repeated).
Unfortunately I rarely see ESPHome developers here in the ESPHome community forum … so I doubt that any of the people Nathans message is for, will see it It also means that accurate up-to-date information is not available, and much of the advice given is based on years-old best practice … such as recommending MQTT.
And I agree … as a former programmer myself, I know that developers would much rather put their time into developing the next great feature, than documentation. In Open Source this is even more pronounced since their time is voluntary. I had one person say that the suggested documentation PR I was most fervent for was “just change for change sake”. I guess because it didn’t add any new feature.
As you say, Home Assistant is improving. Hopefully these changes will filter down to ESPHome sooner rather than later.
“Approachable” is a great goal. But not at the expense of “functional.”
My home systems are complex. Keeping track of all the configuration settings for them is complex. I don’t want an approachable system to manage this. I want something that is easy to configure and manage, once I’ve learned what all my options are.
It’s also important for me to be able to document, back up, restore, copy and past option settings. None of this is possible to a UI-only solution.
It also means that accurate up-to-date information is not available, and much of the advice given is based on years-old best practice … such as recommending MQTT.