Not sure what company you develop for but documentation is almost always a separate department that works closely with developers.
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.
Then it’s “You get what you get”. Which is where we currently are, managed by the devs.
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.
I have the same experience as microfx and his comparison to Linux is a good one because that’s exactly what I noticed multiple times: documentation is written by and for people that have a fair amount of knowledge of Linux.
To be very clear: I’m stepping in here because I’m very enthusiastic about the discovery of HA, it’s possibilities and I’m aware that A LOT of free time goes into it by everyone that contributes to it, for free.
I don’t want to criticize anyone for how things are done and I always hope that it’s possible to remain constructive.
When you start with HA and have no knowledge of home automation and programming, the learning curve is indeed quite steep and if you’re struggling to get basic things to function, the documentation lacks coherence.
The point is of course: for what kind of people is HA intended and is it an advantage or not to make it more accessible.
Just my 2 cents…
So… I have blogged about my setup, its total opposite of documentation lol, little words and tons of examples. Just the way I like it, feel free to take a look at https://www.freesoftwareservers.com/display/FREES/Smart-Home
Would it perhaps be a good idea for 0.116.x, similar to 0.115.x, to be delayed a few weeks and some time invested in a road map and timeline for documentation updates? Maybe getting some feedback from the community on which areas need the most attention? Just a thought.
This is slightly off topic, but I have been meaning to make the suggestion for a while that perhaps release cycles going to 4-6 weeks instead of every 3 weeks would allow a longer Beta, make for less bugs and more time for devs to spend on making sure all the i’s are dotted and t’s crossed, so to speak.
This would include better documentation due to less time pressures of the currently quick release cycles. There is so much to tackle that perhaps it would be a good idea for everyone to slow down for a minute and really analyze how to logically attack it.
@microfx I started here a while ago so I have absorbed a lot, and much has changed over the last few years.
However I found, when I started, that a good idea was to start here https://www.home-assistant.io/blog/2016/01/19/perfect-home-automation/ and then go to here https://www.home-assistant.io/docs/ and read every page.
Yes it could be improved, and it is great to want to help - I have done a little of that myself.
The trouble with a getting started page is that everyone wants something different from their system.
MicroFx- I was where you are a few years ago. If not for the kind hand holding of the experienced users, I would have given up.
FYI- This is the first time in three years that I saw a moderator and an admin post anything. You must have touched a nerve.
And I still don’t know what the domain means in Home Assistant.
I have seen plenty of mod and dev posts!
I think domain is like the category an integration is in, like
climate. The bit before the dot in an
I think what is required (or desirable) is an overview or concepts page.
What is home assistant?
How does it work?
How do I add a light?
A general overview page in other words.
Also, in the Getting Started section it would probably be a good idea to offer up a NUC install as well as the RPi. I know there’s a decent cost hike but if it’s mentioned that you get a much faster and capable system with basically the exact same install method (HA OS), I think a lot of people would go for it. (no SD card dramas, ability to record multiple HD CCTV streams etc.)
I think all references to NUC should be expunged. Any x86_64 computer will work. We are not an advertising agency for Intel.
And yes I know there is a version of HA OS for the NUC and identical chipsets.
Yeah true, if the install works on other machines then sure. I’m not up to speed with what hardware the ‘NUC’ install will work on