I don’t understand anything in the documentation. And I mean it. It is written without good examples. I have no clue what I am doing. Every problem I had so far couldn’t be answered for me by looking into the docs. And most sutff in the forum is also not 100% possible to recreate due to the rapid changes of features etc.
Last time I tried to start with smart home automation stuff I was using openHAB and they had the same problem (a bit more difficult to write correct json).
Totally lost… what can I do? Can I help improve the documentation with someone together who knows how this all works?
It would be awesome if there was an example … how does a entity_id look like? How does a list look like? none? all? What for? Why? Do I need it? I don’t know… better leave it alone - I don’t understand what it is for.
Most of those boxes are like this for me. I need to see examples how to implement it. There are of course plenty of examples but almost never with the content of what is in the boxes.
How does a fully working automation.yaml look like? Do I need to put a automation: into it? Looking at the examples it is not clear. The information is cluttered. And now while compiling the links for this post I found something that is clearly missing being mentioned here and there: the examples page which has better commenting than the actual documenation for my needs:
All I wanted is to filter out my Hue lamps since I have them already with the original Philips Hue Bridge hardware – so HA is publishing them as well – so I’ll have them twice in Apple Home.
The author is writing about Domains … but not explaining what a domain could look like or is. Also I have no clue why it is not working and there is no link to anything that could help. Entity_globs?! It’s like it is written for people who already know everything.
Ah, well I don’t know … completely lost in translation here.
I can help, seriously. But I would need someone who could answer all the questions. Because I cannot.
Edit:
Maybe we can work out a forked documentation for people like me who are not fluent in python, c and rust …? But might be that this is not the intention? Maybe I have to wait until most of the config stuff is being accessible through the GUI?
Tinkerer helps out here all the time, and though most of our moderators are pretty good Tink is exceptional
123 (Taras) is more active in helping than most, but of late we’ve had a number of people that can’t be bothered reading stuff to find what they need, they just want a quick answer.
Maxym is merely pointing out (for example) that ‘you’ don’t know what a domain looks like (I had same issue reading this too) so it would be pointless asking ‘you’ to correct what’s there.
I disagree on the forking the documentation front, either it’s good enough for newbies or its just ‘not good enough’.
This is getting off topic a bit … I quite understand what they are telling me. The question is more: Can I help improve this to help future learners get started more quickly and maybe learn on the way how it all works?
I want to clarify that you mean you don’t understand the term entity_id (the word shown within a “box”) shown here?
You linked to a page explaining the automation.turn_on service. It describes how to use this service. Effectively you linked to a dictionary’s description of a word. How to use that “word” is described in another chapter of the documentation (specifically the one for Automations)
The documentation answers your question here, in the Advanced Configuration section, Splitting your configuration
The examples page is part of the documentation, just on a separate page.
You do realize of course that everything related to a single topic cannot be incorporated in the same page because that would make it difficult to read.
I grant you that ‘domain’ is a term that is not well documented. The only place i know where it is mentioned is in the description of the State Object and even that is an indirect reference (because the topic is the State Object, not specifically ‘domain’).
Those specific references to domain and entity_glob appear to be from the Homekit integration. An integration’s documentation is limited to explaining its operation and configuration, not to explain the fundamentals of Home Assistant and its terminology. Nevertheless, it does provide a reasonable explanation for the use of include_entity_globs here:
Perhaps it could have included something similar for its explanation of include_domains:
Domains to be included. Example: light, switch, etc.
The documentation is composed by the community. It’s constantly evolving, shaped by the contributions of volunteers. If you encounter anything that you feel could use improvement, you are free to add to it. Your submission is vetted before it becomes part of the official record.
Home Assistant is not a consumer-level product. If you have no technical background whatsoever, learning and using Home Assistant will be challenging.
Based on what I just explained, and what you just wrote, it’s entirely possible that Home Assistant is not your best choice for home automation.
This rapidly evolving software project is for hobbyists and tinkerers. If you find the documentation is challenging to understand, you are likely to be overwhelmed by the actual application of what it explains.
Whatever you currently perceive as a hurdle, like impenetrable documentation, isn’t likely to change in the near future. Therefore I strongly recommend that you consider looking at other home automation solutions. It’s important that whatever you choose is easy for you to learn and use. Otherwise, you won’t enjoy automating your home.
There are several other alternates (open-source and commercial), here are a few (in no particular order):
Okay, then. Keep your secrets? It’s not lacking much to make it beginner friendly. And I offered to help. But this seems like Linux where the advanced people say “Why don’t you use linux” – your answer is the answer to this. Because it is not user friendly (explained).
I like home automation more than Home Assistant. I want other people to like home automation as well. That’s why I suggested you look around at the alternatives and find something you like.
I’m being very frank when I say that the kind of improvements you (and I and others) want to see in the documentation, won’t happen any time soon. It would require a significant contribution of time and effort and I have no reason to believe that’s in the pipeline.
Let me help you to help others. But I would need support. A few links here and there and further explanations. A super noob-guide. I am again offering to help. But I would of course need help from you.
I tried a few of the other platforms. HA is best so far. Also I am a tinkerer. But the culprits and the ‘easy’ solutions are too cluttered in the Docs. That’s work. But it’s doable for me I’d say. At least for the simpler stuff.
Feel free to first post a draft version, of the documentation you wish to add, here in the forum. Interested parties can review and provide guidance/commentary. Then you can submit it for inclusion in the official documentation, confident in the knowledge that it has been peer-reviewed. The final decision lies with members of the development team, who review the submission.
If you have specific questions, post them on the forum. Many people are willing to help. I know HA has a steep learning curve, my first steps were difficult too. But with a little help from the forum, I got through the initial steps, and now I can even help others. Just don’t give up to fast.
I will… I have now figured out how important spaces are for the config although all online validator say it’s fine. Thanks for the head-up! It’s the tiny super important information that is lacking in the Doc in prominent positions.
I might not be the brightest light in the room, but I think I have a point here?
