Plus one to that .
4 Likes
which is the case for all documentation sites or forums I know.
IMO the most efficient way to search sites is google search limited to particular address
2 Likes
It’s incredibly hard for anyone else to document your code when “you yourself have the best and entire knowledge of how the code you just wrote works”.
No one else knows what options, capabilities are in your code, how to enable / them etc.
I think it has to be a joint effort.
We already have the developers contributions right now. So…
I have made a few changes to the docs, it isn’t that hard, but you have to learn some markup. Pretty easy to learn.
1 Like
A suggestion: a documentation bug hunt (with a free month of Home Assistant Cloud for the top contributors? 
), or some other form of gamification might encourage more users to increase and maintain documentation quality.
2 Likes
I hope it’s not asking too much, but would you be able to provide a straightforward step-by-step Intro for that? I mostly use github as a resource for looking up things, not so much for editing, and something like this could lower the threshold for people like me.
It wouldn’t address the bigger picture issues that were brought up throughout this threat, but it might at least get more people to fix things they stumble over 
A “how to edit the docs” doc page may be a pretty useful thing to put in the edit docs bottom bar. I think that is an actionable item that would improve experience.
Another mention in this thread is a last updated docs date shown on the page. I think that could be helpful as well.
An addition “was this helpful 
” could help identify poorly done docs pages. The generated data would need to be surfaced, analyzed, and investigated to fully understand the issues but could be a useful way to identify poorly done docs pages.
Already done by someone else 
Editing the Documentation and Creating a Pull Request on Github
But always happy to help if someone asks.
1 Like
You can click on the “edit this page” and it will take you to github, where you can see the entire page history. I agree though that the “last updated” right there on the page would be good.
1 Like
I highly appreciate the activity.
That said, it does not address the core of the problem. It matters not how good a single or collection of pages are, if the concepts, flow and structure of the overall documentation is troublesome.
There are too many concepts and structures that are interlinked in reality, yet almost impossible to decipher this from the documentation.
It is like describing the ingredients of a recipe in detail, but the steps of preparation, why, or several examples are not provided.
3 Likes
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”