Glad my ramblings were helpful.
A few thoughts:
I too would like to be able to improve documentation, but haven’t yet learned how to or gotten up the courage. I think it is possible to be granted access, though I don’t know the edit/review process, to make sure technical details are correct.
This world of development is fast moving and evolving. There are many ways to achieve things, and new options develop frequently (or seem to). After your second bullet point under #1 above:
- I don’t load Samba unless I specifically want to edit files from an editor (I use Atom) from my Mac. Instead I’ve started using a web-based add-on.
- Since installing hass.io I have rarely accessed SSH, unless I’ve managed to blow up HA so it won’t even launch, which is startlingly easy to do. When I make changes I check my config from the Configuration | General page in the frontend.
- To restart I go to the Hass.io page and click the three dots button at the top right (Restart Home Assistant).
- On that Configuration | General page I mentioned, you can reload several components to immediately see the effect without having to do a full restart (e.g. when I’m playing with my groups.yaml which affects my frontend I Reload Groups and the Overview page reloads with my new setup).
When I was starting I downloaded the Atom editor to my Mac, and prefered it to Nano for editing files via Samba because of the UI and syntax highlighting when editing yaml files. But now I get a similar interface directly in the web IDE I linked to above.
- I don’t think discovery is unique or special to hass.io. It’s a core feature of HA (correct me if I’m wrong).
- You need to add a device to configuration.yaml, if it is not auto-magically discovered, or if you want to further configure it. For better or worse, the default assumption in HA is, “if I find it, I’ll show it to you on the frontend.”
- I’ve hidden a lot of stuff via the customize.yaml and customze_glob.yaml files. For example, one of my zwave light switches puts out about 6-8 “sensors” which are useless to me day to day.
- When you do start to configure your frontend manually, NOTHING will show up until you put it in the right group. So if you get some new device, it may be an entity on your entities page, but will not be on your frontend, until you manually add it to your groups.
I’m trying to give my perspectives and answers as a fellow user (my “lessons learned”) since I shared many of the same challenges, and continue to struggle as I push forward (struggle is maybe too negative. It’s a challenge that I take on.). Hopefully, others will read and learn from us. For my part, I think there needs to be a better selection guide for new users to help them decide on which installation method to use. I didn’t discover hass.io until a month or two after I started, and was thrilled when I found it and finally understood what it was.
But to your larger question, since you and I are not accomplished developers (I presume), how do we use our other capabilities to fix documentation issues and help those who follow? I think we need to reach out to the makers and find out how we can get involved in that as a project to aid the community.
[addendum]
btw, I think there are other options for editing frontend, automations, etc. from within the Configuration page, but I’ve found them not as useful so far. Point being, there seem to be many ways to avoid Samba and SSH, but they’re not as effective or easy as I think they were hoped to be.