100% agreed. But the development within this thread doesn’t get my hopes that high, so I at least might want to start somewhere I guess :-/
Anyone change change all of those things though, not just developers. It does require a little more leg work because you can’t do that in githubs UI.
I have often thought that an “introduction to ha concepts” page would be great.
2 Likes
there is a glossary that people gloss over
3 Likes
Writing documentation is a specific trade. A developer is not proficient to design the architecture of the documentation. It is a full time job most probably for several people. The very first thing that should addressed is: what are the documentation needs? What is the goal of each pieces? The current documentation is more or less a reference documentation. I’ve been using HA for almost a year now, I find it very hard to grasp the languages logics. As someone said this is a giant task. Despite that, step by step, with the help of a very helping community one can achieve what he wants.
4 Likes
I have been using HA since 2016. I am probably lucky to have seen it grow from a system that I more or less understood to being something I more or less understand, but less so than I used to.
The point is that as I have seen it grow I have followed the changes and grown with it. If I came in now, I think it would be harder to grok.
A tip for those who are starting, read the docs from start to finish. Start here Configuration.yaml - Home Assistant and read all those links down the right hand side, don’t worry if some of them are beyond you, or don’t interest you right now, skim over those ones. But at least know they are there.
Then hang around on this forum, read posts that sound interesting.
In short, involve yourself. Don’t expect a takeaway, or a 3 course meal. HA requires buying some ingredients, putting them together and making it your own. That is always much better than anything you get as a quick solution (the takeaway) or someone else’s idea of what you want (the 3 course meal).
2 Likes
Okido, let’s see if this is a bad idea, but well: i’d like to try collecting more concrete examples where people run into a wall when trying to work with the documentation as it is. If you have something very concrete that you remember, please add it here: Share your CONCRETE struggles with the documentation!
edit: the fact that I felt that no category in this forum fit the topic, and it was then moved from “uncategorized” to “social” (“Christmas present wishlist”, “Tibber invitations”, “Greetings from Chile”, …) says more than this whole thread alltogether 
guess the new Subview would be a fine example of lack of proper documentation, especially how to use those in Yaml mode and over multiple dashboards.
The available documentation is correct, but it’s simply not complete.
discussed this already in the beta cycle, a promise was made, but unfortunately not fulfilled.
(leaving me with a hidden folder of collected subviews as a repository I can link to from any dashboard, hardly the preferred way I gather)
Let’s not forget documentation is not only about backend integrations, but also about frontend.
as another fine example: just try to find some docs on the Resources and what they are/do. Searching via the searchbar doesnt show you the way, and I favorited it for my self to be in Multiple Dashboards - Home Assistant so I don’t forget.
explain that to a newcomer…
Tbh I wouldn’t agree on the stance that the code writing is up to the devs, and the doc writing is up to someone else… How would that someone else know all of the intricacies of what’s to know… A translator might be required though to reword the coders documentation into useable guidelines 
it would have changed:
Cards provide a structure for interfacing with your dashboard.
to
Your dashboard is made up of Cards
…
money/mouth change wording of Cards by Mariusthvdb · Pull Request #24647 · home-assistant/home-assistant.io · GitHub
4 Likes
You’ll notice I said “improve” 