This. Absolutely.
I’m slowly getting to grips with HA as I have some time to work on things at long last for personal reasons… but it’s been a massively frustrating experience.
It’s an easy path to take that “everyone understands this”, but even finding out where to edit configuration.yaml and what needs to go in there seemed to take longer than it should do, and the structure of YAML needed to adapt any dashboard can be difficult to understand particularly when the examples given (both in the documentation and other times in threads on here) are incomplete or lose their indentation because they’ve been broken up into blocks for reasons of explanation.
Despite claims earlier on in the thread, fluency in Python does not equate to the same in YAML - I’m a pretty decent python coder (I’ve created some large systems which are still in use years later), but YAML is inpenetrable to me. Yes, they both use indentation but it’s far easier to parse mentally in Python, particularly where the syntax is not clear - which is the biggest issue for me.
I haven’t found any definititve resource which says what is acceptable for any given blocks/mappings. The HA documentation on it [1] is not very helpful and relies on implicit knowledge. And there is a huge lack of simple, worked examples with ‘this is the code you need and this is what it will look like’ in a lot of places. It reminds me of Django’s documentation which makes it difficult to find the actual API reference (which is what you need once you know what you are looking for) and I’ve not found that - to my mind there should be a tree-like documentation structure which allows looking up (say) what is below views: or any other YAML, so you know what is currently implemented.
The editor in HA leaves a lot to be desired, IMO - the feedback is difficult to parse, and an upgrade to something more dynamic here would help, plus the possibility to revert to the previous successfully-saved version at a single click when you’re 8 attempted saves deep and you’ve still not fixed the issue. I’m finding the only way to be less frustrated is by using an external editor and saving the last version in that… which is really sub-optimal. There may be a good replacement for it (or working remotely in VSCode) but again, defaults are important, particularly if you are a beginner.
Don’t get me wrong, when things work it’s great! But there’s so much that you need to do in YAML if you want to get beyond the basics, and this area is largely impenetrable without gaining skills in multiple areas simultaneously.
And that is not a good recipe for learning. I was a classroom teacher for 30 years, and judging by what I’ve been told recently, I was pretty good at it. And giving simple, workable examples which are explicit and complete is important as that scaffolds the learning that people need to get really into this. Without it, the community is losing people who could be brilliant at this. But if you spend 2 hours wrestling with something and getting nowhere, there are a lot of people who will just give up, maybe for weeks, months or even forever.
And having been one of those people who died on the hill of ‘Programming the Z80’ by Zaks in the 80s because I didn’t have the talent of Matthew Smith, I know that it can take decades to get back into an area. Particularly if the first comment you get when you’re frustrated and asking for help is along the lines of “Home Assistant may not be for you”.
I would love to produce such documentation, but I’m short on time (I have a terminal cancer diagnosis, hence my spare time), and I don’t have the YAML knowledge yet to produce anything anyway. What I’ve learned over painful sessions over the last few weeks has transformed my HA installation, but I’m bloody-minded sometimes and really want to get things working.
I also think there seem to have been a lot of breaking changes in the YAML API given some of the older examples I’ve seen don’t work any more, but I’ve not really looked at that in detail.
No flames please, all my opinion. I love HA, but YAML is not friendly, and a lack of a live-editor which shows what’s wrong, and a lack of API reference makes it much more painful than it should be.
[1] - YAML syntax - Home Assistant