Yes exactly, I will do that.
Have sympathy for the newbies - most of the questions we ask are answered somewhere in the vast Home Assistant documentation, and with more experience and 20-20 hindsight it may seem obvious where we should have looked. But when you are first trying to answer a question, you have no idea where to focus to find the solution yet. You face a huge amount of sometimes-conflicting information from different sources, often incomplete or without context, sometimes out of date and no longer valid. Thank goodness we have helpful people to answer questions in these forums. It may just take a little hint from someone with more experience and context to point in the right direction.
I think it’s really hard to write a “beginner’s guide” to anything after you have gained more experience unless you look careful notes about each issue you encountered while you were learning. Afterwards when things seem obvious, you may have forgotten the issues, or they just seem embarassingly obvious now that you know. 
3 Likes
Check my profile; no shortage of sympathy.
Community member @flamingm0e often provides the correct solution for ‘conflicting information from different sources’ and that’s to refer to the documentation and stop following videos and blogs that are many months old. Home Assistant is evolving rapidly and the only sources of information that stand a chance of remaining in sync are the docs and this forum.
2 Likes
I always try to look at the official documentation first, and it usually turns up at or near the top of any Google search anyway. It usually has the most reliable information, and some effort has been made to mark outdated articles as outdated. But you can’t rely on it as your only source. Often the official documentation is short of examples that you need to see, forcing you to look elsewhere, or it lacks some vital context that the reader was assumed to know. Examples often have to come from those long threads where someone posted that their configuration isn’t working, and you have to read through the whole thread of differing answers and untested solutions to try to figure out which advice was correct.
2 Likes
That’s why I encourage users to mark the post containing the solution (or the post that led to the solution) with the ‘Solution’ indicator. It will automatically place a checkmark next to the topic’s title (indicating the topic has a solution) and, more importantly, it places a link below the first post in the thread that leads to the solution post. This makes it very easy for others to locate the solution (with having to scroll through all the posts in the thread).
Maybe so but this time it was covered in the documentation for Splitting up the configuration. That’s a procedure you do deliberately, not accidentally. The documentation even includes a troubleshooting section.
Anyway, if it’s not abundantly clear by now to all readers then here’s the ‘in-a-nutshell’ version:
Don’t put two or more identically-named domain sections (
automation:,sensor:,switch:,light:,script:, etc) within the same configuration file or across multiple configuration files.
I can’t disagree with any of that, but I would just remind documentation writers that people researching a problem and arriving from Google haven’t necessarily read thoroughly all the official documentation they should have, and they may have jumped into the middle of this document without following the intended path. It never hurts to provide as much context as possible, and as many explicit examples as possible.
One of my pet peeves with Microsoft Office for years has been that their Help writers don’t provide context. They will give you a full page explanation of how to use a function - but forget to tell you where that function is on the menus!
2 Likes
“Documentation writers” is the community. Everyone is welcome to create a Pull Request to submit new or modified documentation. It’s a volunteer effort.
What you’re suggesting is write detailed, comprehensive documentation targeted for people who … don’t bother to read documentation. When they do, they skim it. I suspect there aren’t many volunteer writers willing to waste their time addressing this demographic.
If you’re willing to do it, kudos to you.
No, that’s not what I am suggesting.
I am suggesting that documentation writers should realize the simple fact that few people actually read their very fine documentation all the way through from the beginning in thorough detail the way they intended. Real people are more likely to skim, jump into the middle, look for a quick overview etc… For that reason it is more important than the writer often realizes to provide context and not make too many assumptions.
It’s like reading travel directions that say “It’s simple: you go straight for 10 minutes, turn left where the big tree used to be, and you can’t miss it on the right.” - without saying what your starting point is, what mode of travel you are assuming, how you would know where a now-missing tree once was, and what is the “it” you are supposed to see on the right.
It’s not Microsoft Office, it’s not travel directions, it’s a community-run software project dealing with (frequently) complex software configurations. This is a software product for home automation enthusiasts, hobbyists, and tinkerers. Effectively, it’s a constructor kit that you assemble to create a personalized home automation solution.
Anyone unwilling to read the available documentation (not merely skim it) or read the many tips and examples posted in the community forum will have a very difficult and unpleasant time using Home Assistant. FWIW, openHAB (another community-run home automation project) is no different in this regard.
Then they have chosen the long, difficult, frustrating way to learn Home Assistant (or anything else for that matter).
Like I said before, no one is rushing to write documentation for people who choose not to read documentation.
That would be US, the community.
What EXACT context would you expect in every situation? With every setup being different, what makes sense for context?
I can’t say what EXACT context should be given for each bit of documentation, flamingm0e. There are many small things that a documentation writer could do to make context clearer. For example the Microsoft Help case I mentioned where the common fault is that they explain the function in great detail without mentioning where to find it on the menus. Or a common Home Assistant case where the author gives specific example configuration code, but doesn’t say which file it goes in, clearly assuming that the reader should know.
It’s not my intention to criticize, and obviously we should all be grateful for the efforts that people put into a valuable open-source project. This is just my own view that being able to maintain the perspective of a new user who lacks your context, and putting a little of that perspective into the documentation, can help make it much more accessible. After all, our hope for any open-source project is that it will invite more users in rather than becoming a closed community of experts.
By reading the documentation, you would know it goes in the configuration yaml, unless otherwise stated.
I think every component/integration I’ve looked at has actually stated configuration yaml…
If you want a specific example, I was was looking at some examples of “customize” section settings because mine wasn’t working, but several of the examples failed to mention whether their configuration fragment was from the configuration.yaml file or the customize.yaml file, where the problem was that the indentation was different between the two locations.
There are many other configuration files in Home Assistant besides configuration.yaml. A new user doesn’t know what they all are or how they are used. When researching a new topic, you don’t necessarily know if what you need is a new section in the configuration.yaml file, or a section in one of the other files. Example fragments don’t always make it clear which file they go in, because the writer knows that they go in a specific file and nowhere else, so there’s no need in their mind to identify the file.
As @flamingm0e wrote every example is for the configuration.yaml unless otherwise specified. Nowhere on this page a customize.yaml file is mentioned.
Not unless you split up your configuration which has been mentioned before in this topic.
It’s all in the docs.
This discussion is so long, that I thought I could contribute with something:
Sometimes when you start a project you are anxious for having some results. You are, in a certain way, testing yourself to see if you want to proceed. In my case, I was testing 2 platforms at the same time: OpenHabe and Home Assistant (I now decided for Home Assistant exactly for the better support community).
Being capable of controlling two off my shellys, in the first day, installing a zigbee network, a sensor, and making the first automation by the fifth days, was a big deal for me, as I’m not from the computer science world, I’m just an architect curious about experimenting and making things in is free time…
When English is not your language, is painful to read a lot of technical text and acronyms… Especially acronyms!
For me, the harder part, was the basic concepts, location off things and how to connect to them… In few days I had to learn to work with, my mac terminal, SSH connections, connect to my files in the raspberry by SAMBA etc etc…
I don’t sink this woold be possible, just following the book and read about every thing before trying anything…
Finally, you do can have lunch alone, but is nicer to have it with your wife or friends… Hear is the same.
These days everything is on Google, but let permit ourselves to humanize it a little…
Wen I looked on HA log it took me 5 seconds do understand the problem, but the truth is before I didn’t even know very well what a log was…
Tanks a lot for all the support and time, it was precious to me, I hope to be capable of help someone in the future.
1 Like