Hello,
it’s again about the documentation per se:
As a beginner, you read through the forum and the respective documentations. What I’m primarily missing is a kind of label, i.e. a small summary block of information at the beginning about, among other things, the respective type of integration, dependencies, affiliations and properties, which Python libraries may be required and installed, HOW it may be integrated into the yaml as an EXTERNAL file - I like to keep it tidy and clear.
Also information about what type of object it actually is (domain, class, parameter, command, identifier, value, etc.), for example whether a hyphen has to be prefixed, etc. Short general example codes (due to the integration), including the higher-level blocks.
I also miss an overview of which objects represent a domain, which represent a class, etc.
For example, in Python there is a list of important words. Something like that. And of course this is mentioned in the label…
By the way: who can briefly write down the structure of a yaml for me like this:
Hi Tom,
Thanks for your answer.
If the documentation was easier to read/understand for beginners, I probably wouldn’t write such crap here (apparently).
So the concept is ‘try and get lucky’ ?
I don’t think everything is in the documentation, otherwise it would be easier for me.
Just copy code snippets and paste them somewhere (it doesn’t describe ‘where’ and ‘how’), I don’t know…
I often get references to the documentation for developers when everyone is supposed to be able to use HA. If you want to make individual changes, the corresponding sensor must first be implemented. But I don’t know which sensor and how, it’s not mentioned anywhere…
The label, I think, is important because otherwise you have to read the whole documentary all over the place and in the end you only understand ‘train station’.
In any case, your answer was disappointing for me. Ok, that’s life…
Thank you for your time and effort. HA is really great. Thanks for that.
Hello Peter,
Thanks for the link to the cookbook. I’ll keep an eye on it.
Do you want to see a schema definition for how HA uses YAML?
Yes, Peter. At the moment I have no idea what I can ‘program’ myself, how I can write templates, etc., or how various problems can be solved. It’s difficult to describe and even find the right terms if you don’t have an overview or perspective. But that’s the case everywhere.
In any case, the documentation didn’t give me any insight…
Definitely more information in general about how to integrate something.
There is the GUI, but for scrape, for example, the yaml integration is recommended and scrape cannot be seen as an integration in the GUI.
Well then. Thank you for your answer and your time.
You’re talking about many different things, in different directions.
It’s very hard for any kind of documentation to work for everybody and what they’re unique needs are.
You should see HA as a box of LEGO: You learn what pieces exist and how they can fit together to build something, but you don’t get a plan/recipe for anything that can possibly be built.
Maintainers can choose. Traditionally, it was all YAML, but then the UI capabilities were added. They can support both options, or just one. It’s really a different issue – and these things are documented quite well.
In my opinion the documenation needs a real getting started area. Currently, the getting started area is just about the installation. That section needs to continue through a series of pages that cover:
Configuring and adding your first device through an integration using the UI.
Configuring and adding your first device/entity through an integration using Yaml.
Setting up your first automation.
Throughout that process it will use keywords that link to the glossary of terms.
The rest of HA can continue to be a technical reference.
Oh and the automation sidebar section needs to have Conditions and Actions link directly to the list of conditions and actions instead of an intermidiate page that’s easily glossed over. Those pages are pointless and do not add any help, they likely should be added at the top of the list of conditions and action pages.
Been working with HA for at least 4 years, and I agree it can be a pain to find implementation details. The forum does include “community guide” and “share your project” categories. I think a little curation of the community guide section would be helpful. I’m always wondered why their wasn’t some means for the community to identify threads that should be elevated to a community guide. Some threads should probably be demoted from community guide level. A way to organize community guides beyond advance search filters would be helpful. Maybe a table of contents like page where community guides that are related to the same topic are grouped. There should be a list of guides for subject matter that forum members would like to see built out. Maybe people could vote on these missing topics, thus encouraging others to document them out.
So why isn’t the cook book mentioned on the Home Assistant main page or Getting Started link. It would seem appropriate the cook book would be identified somewhere so new uses could find it. Maybe it should also have a prominent mention on the main forum page.. Maybe it’s somewhere, but on my quick look and search on those pages I can’t find the cook book mention. In all the time I’ve spent on the forum, this is only the second topic where I’ve come across the cook book. Is there a way for it to always show up at the top of the community guide page? I think this thread is about helping direct people to useful information. So if the cook book is the answer then it needs to be elevated out of the ocean of information. Everyone that enters this forum should be aware that the cook book is the place to start. Maybe it’s just me, but I didn’t know it was.
So the community wants people to find the cook book on their own with no expectation that it’s seen as a good starting place for information? I think the point of this thread is to make it easier for people to know where to get started. So elevating something like the cook book to a more prominent place would seem appropriate. Adding mention of the cook book in this text pulled right from the main forum link might be reasonable.
Community Guides
The Community Guides section is a place to share guides/tutorials with our community. Every post/topic in this section works like a Wiki and can be edited and improved by anybody. Please note, guides provided in this section may be outdated/broken and are not supported by Home Assistant.
I didn’t realize we were arguing. It seemed you were pushing back on the posts I made and so I was making simple suggestion that might help move this forward. I was just offering up alternatives to a full robust solution. A full getting started area would be great. If that doesn’t happen then some simpler alternative would be good.
