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.