Request re documentation

Newbie-alert! I started using HA (hass.io) a few months ago and now have a stable and working installation, and it’s also a lot of fun!

I would like to share some newbie experience, especially about the documentation here on home-assistant.io. First of all: from several opensource projects I have used, the HA documentation is one of the most complete, up-to-date and searchable. It helped me a lot, thanks to every one that contributes!

But there is one thing I would like to address: the documentation almost always contains snippets of scripts but very often it is not mentioned in which file or location those snippets should be stored. Is it in configuration.yaml, automation.yaml, ui-lovelace.yaml, scripts.yaml, secrest.yaml or somewhere else? And does that file has to be stored in /config, /config/custom-components, /config/www, or (again) somewhere else? Working on the configuration of hass.io I often have to make an more-or-less educated gues and several times had to find out the guess was not educated enough.

So therefore my request: it would help a lot when in the documentation with every snippet of script or code the filename and location where that snippet has to go is mentioned …

More general: I would expect that a great deal of the documentation is written by HA pros, who (while doing wonderfull work) seem to forget to note down the for them obvious details. But for noobs like me they are not so obvious at all. You are all free to use me as an example: I had some initial training in coding in the late '80s (algol68!) and did some PHP scripting in the '90s and have used linux in some situations, but I am more a guy who knows how to read howto’s than really has a deep understanding of how it all works. So: the more obvious details, the better, as far as I am concerned.

The great thing about collaborative open source projects like this is you can make these changes yourself:

It’s really not that difficult. If you can get Home assistant up and running you can do this.

However for this sort of site wide change I’d suggest you propose it on the documentation discord and get a feel for the acceptance of these changes (and probably some help managing/performing it - it’s an easy but big task) before diving in and making them: https://discord.gg/5dpaAf

3 Likes

I know, I can do more. But at the moment I am just not confident enough to edit any of the online documentation. I just wanted to show the perspective of an noob, and it was certainly not my intention to complain!

Maybe I should mention what triggered me to post the 1st message: I am trying to integrate a Google Home Mini (and therefore Google Assistant) into hass.io, and I have to say the documentation is very hard to follow …

Perhaps a specific example of what you think is missing would be better