I approve, but I would encourage placing any advanced topic within the docs of the underlying component. This would seriously simplify navigation and I think help other see the big picture.

I agree with that, I think that breaking component docs into subsections would help tremendously. We already do this for Z-Wave but I feel like MQTT could use that too

I'd also like to add that platform docs aren't obvious.

My thoughts; advertise all the platforms as we kind of do on the components page already, but upon selecting a platform some information/description is displayed before the list of individual components - with a link to further platform documentation.

Initial thoughts.

• The biggest barrier is how daunting the config can feel. The Getting Started section should get the person to a clicky usable thing in as short as possible. Discovery in components is huge for this. Focusing on RPI3 should also be prioritized. If 80% of 70% of users go that route it's a large portion of the userbase. A step by step with a copy and paste generic config could get someone new going in 5 minutes.
• Config 101 is important. Personally I like having my files split up and referenced by the main config. I didn't even know this was an option until I ran across it under examples.
• I love the idea of platforms and then components listed underneath. When I'm looking to do something I frequently have to check both the platform and then the component.
• An automated way to show which options are available for which component would be great. It's already defined in the component but I've had to poke around in the code to see that the Flux Led doesn't support color_loop for example.
• Automation is another barrier. Examples showing how to reference components using Jinja2 would be very helpful.
• A Tools section. Show the purpose of the developer tools and how to use them.

Another thought I had was an ask HA blog. Have users ask questions about how to do something and write it up as a blog post. These could be archived as examples of what you can do and how to do it. I'd be happy to help with it. Weekly might be too frequent but monthly should be doable.

I'd be happy to contribute some of my configs to a config 101 if so desired. Something we find (or I at least) in the "support" chat (to the point that it's become a awful joke) is how to post formatted code snippets (e.g. between 3 backticks). Perhaps it might be worth having a template of sorts (what to include in a help request. not mandatory but recommended) or a primer on some of the eccentricities of markdown.

With regards to ui, would having expanding blocks (I think they're called accordions) separating the basic, intermediate, and the what the hell have I just done in the same page but have the upper levels compacted by default.

Would it be worth having a FAQ section based on the questions that pop up often either in chat or the forums.

Ok, that's enough rambling. Time for bed.

@bassclarinetl2 currently the configs in the docs are only maintainers, but I can't personally see any problem with adding a community section with links to various GitHubs and a short desc.

@balloob great ideas, that would make a lot of sense.
Especially when you look at the Automation section of the Getting started guide, you are pretty overwhelmed. Then again, the Components → Automation falls rather short. I think it should be swapped, a getting started with a few meaningful examples, easily understandable, and the full documentation with good explanations of the configuration variables in the components section with a lot of advanced use cases.

Is this still a valid issue @balloob?

Last remaining issue splitted out as #3477.