Based on the posts in this topic, I would suggest:
Lastly, to keep in mind that hundreds of thousands of productive users have preceded you and they referenced the same documentation (actually, an older, less comprehensive version).
I see that the response to “why no date?” is “nobody wants to fill this in all the time.” The date on page means that content is valid for the current environment, but not necessarily for any future environment.
Don’t get me wrong, documentation is hard, and tedious. As noted about “last update” It’s not done “because nobody likes to do it.”
Here’s something that would be easy to do. On the page Concepts and terminology add a section like this:
Must read reference pages
Basic Home Assistant YAML
Glossary
Index of functions, concepts, configuration, etc.
Some Recipes (a cookbook)
The author of the Index notes “Documentation is extensive, but not easy to navigate - hence this unofficial index.”
Well go ahead and add it then.
Personally I think the documentation of HA it’s actually very good. I remember I was quite impressed about it when I first started using HA. I found most basic things to be explained well. I recall I was mostly irritated by the search function, which would often show as first results some random integrations that used the searched word, instead of the article with that word in the title. But I think that was fixed with the new interface.
What I still struggle with is templating and I wish its documentation was expanded on the basics (instead of just looking the Jinja2 docs). But then this is quite advanced feature, so you could say it’s expected it won’t be covered in step by step tutorials for newbies.
This “search” function deserves its own wth
There was a plan at one point to make it more broken apart for each function/filter/test etc but it’s a massive undertaking
I did provide it as feedback, in hopes that my feedback would be reviewed, found useful and incorporated. Wisely, not everyone can make the changes though one could create a fork. I choose not to fork because a fork would add confusion.
-OSD