Home Assistant is not a consumer-level product. If you have no technical background whatsoever, learning and using Home Assistant will be challenging.
Based on what I just explained, and what you just wrote, it’s entirely possible that Home Assistant is not your best choice for home automation.
This rapidly evolving software project is for hobbyists and tinkerers. If you find the documentation is challenging to understand, you are likely to be overwhelmed by the actual application of what it explains.
Whatever you currently perceive as a hurdle, like impenetrable documentation, isn’t likely to change in the near future. Therefore I strongly recommend that you consider looking at other home automation solutions. It’s important that whatever you choose is easy for you to learn and use. Otherwise, you won’t enjoy automating your home.
There are several other alternates (open-source and commercial), here are a few (in no particular order):
Okay, then. Keep your secrets? It’s not lacking much to make it beginner friendly. And I offered to help. But this seems like Linux where the advanced people say “Why don’t you use linux” – your answer is the answer to this. Because it is not user friendly (explained).
I like home automation more than Home Assistant. I want other people to like home automation as well. That’s why I suggested you look around at the alternatives and find something you like.
I’m being very frank when I say that the kind of improvements you (and I and others) want to see in the documentation, won’t happen any time soon. It would require a significant contribution of time and effort and I have no reason to believe that’s in the pipeline.
Let me help you to help others. But I would need support. A few links here and there and further explanations. A super noob-guide. I am again offering to help. But I would of course need help from you.
I tried a few of the other platforms. HA is best so far. Also I am a tinkerer. But the culprits and the ‘easy’ solutions are too cluttered in the Docs. That’s work. But it’s doable for me I’d say. At least for the simpler stuff.
Feel free to first post a draft version, of the documentation you wish to add, here in the forum. Interested parties can review and provide guidance/commentary. Then you can submit it for inclusion in the official documentation, confident in the knowledge that it has been peer-reviewed. The final decision lies with members of the development team, who review the submission.
If you have specific questions, post them on the forum. Many people are willing to help. I know HA has a steep learning curve, my first steps were difficult too. But with a little help from the forum, I got through the initial steps, and now I can even help others. Just don’t give up to fast.
I will… I have now figured out how important spaces are for the config although all online validator say it’s fine. Thanks for the head-up! It’s the tiny super important information that is lacking in the Doc in prominent positions.
A lot of the old posts from prior to mayish (might be off by a month or 2) 2020 were prior to the ‘website search’ changes. You couldn’t search the site for ‘default config’ so your fallback was to ask here. That’s all changed now and the search functionality is useful. As for the topic at hand…
Personally, I’m with you on this subject. The doc’s need some love and reorganization. Any input you have is welcome. I’ve always thought we needed a “Getting Started” section that just hammers through the doc’s in the correct order. We also might need an update to the glossary section where we can cover things like “domain”, “entity_id”, etc. Then we can add links in the documentation wherever those keywords are used.
This is one of those chicken and egg problems. By the time you know enough, you don’t see the problem any more. It’s only those new to HA who really see these problems.
We need the help of the “newbies” to improve the docs. Sometimes it’s within their ability (edit the docs once they learn), sometimes all they can do is flag it up as confusing.
I’ve mentioned it elsewhere, but the project has reached the point where the docs are primarily a reference manual rather than a user guide. It really needs both, but writing that user guide isn’t a small task and nobody has been brave or crazy enough to pick it up, yet.
I cannot agree with this. I’m a developer so I understand your point incl the difficulty of writing usefull docs by author of the software (for whom most things are obvious therefore doesnt deserve a more detailed description.
But IMO, the developer is responsible for creation of meaningful documentation. One which provide all possible information in as consistent way as possible.
Yes, it’s usefull to engage newcomers after they get grip on the software. But we have situation here in which the person is not able to even to collect basic information to start with because, and let’s face it, the HA documentation is often very laconic, and/or pages to refer terms which are not linked with their documentation. The last mentioned issue is also a reason why it’s far away from reference documentation
And what if there is no such department? Whar if sf is created by single person, or team of friends who are programmers? Does it turn into no documentation?
At the end a user really doesn’t care about who created documentation. For him it’s software provider/creator aka developer.
Typically in my experience this happens in smaller companies, and the end result is poor documentation that includes a lot of assumed or tribal knowledge and looks a bit like the documentation that HA has.
I think I feel the need to apologize for the others “if you can’t figure it out then move on or fix the docs (even if you have no idea WTH you don’t know)”. this thread really took a bad right turn somewhere.
Tinkerer is at least correct that by the time you figure stuff out then you can no longer see a lot of the issues with the documentation or don’t really want to spend the time to dig in and update it.
If you’d like some help feel free to PM me. As long as you are willing to spend the time to update the docs from a newbie perspective after we’re done I’ll try my best to help you figure stuff out.
I agree with you @microfx, the documentation can use a lot of refinement. I don’t think it’s beginner friendly at all.
It hasn’t kept up with all the improvements to the UI and UX over the last two years. Just from a quick glance, the “Zone” integration docs for example doesn’t mention the Zones GUI editor at all, and that feature is now like eight months old.
There’s plenty of examples like that all over the docs. The Lovelace card pages don’t really mention they can be edited from the user interface, etc… It often makes Home Assistant seem significantly harder to use than it actually is. I bet there’s a lot of beginners following outdated or lacking documentation and actually making things harder on themselves.
Getting started section should be significantly expanded I think. It guides you through the onboarding and creating a basic automation, then tells you about presence detection and that’s about it. There needs to be more there, walk the user through some of the next steps in order as Petro said.
The cookbook/examples need to be updated as well. Many of the examples use random third party services, the “send notification based on sensor” example should use the official Home Assistant mobile app rather than pushbullet. The “automation for rainy days” example uses Dark Sky which new users can’t get an API key for, etc etc.
There’s a bunch of other things that are barely documented at all, even core concepts like Areas. I don’t think the structure is great either. I disagree with the way the “Topics” right sidebar is laid out. It is pushing “Advanced Configuration” and explaining things like Jinja templates and SQL Databases before the basics (Automations, Scripts, Scenes, etc).
IMO the documentation needs a significant overhaul. But no one has really stepped up to tackle this yet. A few people collaborating on this could make an enormous difference. If you want to try and help, I’m sure many would be happy to answer any questions you might have. I would check this out too: Editing the Documentation and Creating a Pull Request on Github.
@finity Totally agree. Although I don’t see a wrong turn. Quite productive conversation here. Not often held. Thanks a lot for your offer. I will definitely do this.
@SeanM Yes, I can totally agree. And I think it is inevitable to start from scratch. There should be Guides that are easily understandable and more or less failsafe – even for my grandmother. With lots of Screenshots and complete configs. It is really not too hard to become good in HA. It’s just the tiny bits of knowledge you all have learned in a few decades of using HA / coding / tinkering with linux etc. pp. and or you are just smart
What do you think? I am willing to help where I can with ideas, screenshots and writing and the most important extreem noobism . But I would still need lots of help because I am not even scratching the surface with this super awesome software! Can’t be said enough.
I totally agree. I had a lot of issues as a new user (still some when I try something new). My big issue besides not written for a new user is there is zero document control. I have mentioned it before and I was told that this is to hard to implement. Without this I believe the documentation will never be done correctly.
I also had this issue the first few tries getting HA going. At one point years ago I gave up and learned JS/NodeJS to write my own front end for my Particle devices because that seemed easier (it was fun, but not easier).
Anywho, I’m lovin’ my HA now, and excellent docs are always a great idea.
. But I would still need lots of help because I am not even scratching the surface with this super awesome software! Can’t be said enough.