Tutorial feedback

[loudenhugely]

Feedback

Hi, Thanks for the guide for beginners. My impression is that it needs to be much more in depth. For instance, "click the “Add integration” button in the lower right and search for your integration in that list." As a beginner, I didn't know what an 'integration' was. I had some Meross plugs. I didn't know I had to add the "Meross Lan" before adding them was possible. There are just too many steps that are skipped and knowledge that is assumed for it to be truly useful as a beginners' guide. I keep running into this. I'd offer to help, but I know Zippo about any of this - luckily I have a friend who is guiding me too!

URL

https://www.home-assistant.io/getting-started/onboarding/

Version

2022.6.0

Additional information

No response

[ndudde67]

Agreed. I think part of the problem is that the web page design doesn't consistently provide a linear path to follow. For example, https://www.home-assistant.io/installation provides very little in the way of page navigation on the right side of the page, but https://www.home-assistant.io/docs/configuration/ includes links to the next steps as well as a link back to "Installation." I'm aware that the installation info is specific to the HA platform, but the page navigation could fork for each platform's installation instructions and then merge at the point at which the user completes installation. Also, the Integrations page should link to a how-to or give user direction of some kind.

[dannytsang]

Hi @loudenhugely and @ndudde67

Thank you for the feedback. There's quite a lot of information so I would like to breakdown the problem and stick with @loudenhugely original feedback so I hope @ndudde67 don't mind and maybe raise a separate feedback/issue.

If I could use you and anyone else interested as a sounding board and feedback before attempting to make the changes:

As a beginner, I didn't know what an 'integration' was.

If a new page was added called about integrations between Onboarding and Automations would that work? The page could explain what an integration is and an example of how to add an integration? Current navigation:

I didn't know I had to add the "Meross Lan" before adding them was possible.

This is a tough one because it will depend on the manufacturer, product, integration maintainer as to what it can be called. It's like people refer to the device Alexa when the physical device is called an Echo and Alexa is the (software) voice assistant. Do you have any suggestion on how guide people on this?

There are just too many steps that are skipped and knowledge that is assumed for it to be truly useful as a beginners' guide

Apart from my proposed Integration page above, are there any other steps or information you would like to see?

[ndudde67]

If anything, I think such a section should be the first section, before "Installation," and should cover every single feature (briefly) mentioned in the "Compare Installation Methods" chart on the "Installation" page. If a user doesn't know what each of those features are, they can't very well be expected to make an informed decision on how to run a HA instance. Additionally, an "Integrations" page (covering the topic in-depth) should be in the "Documentation" section.

Essentially, my overall feedback is this--IMO, the best way to present information in an easily digestible manner is to stick to two principles:

1. Website layout consistency and linearity
2. Provide topic coverage at both high- and low-level depths so that both new and experienced users can easily access pertinent info.

Ideally, I'd suggest that the menu ribbon at the top of the HA page have a drop-down for both "Getting Started" and "Documentation." This could eliminate the need for page navigation on the right side of the page which tends to not scale well if the navigation list is long. Additionally, as stated before, there should be something like an "Overview" section before "Installation" that covers the major topics in brief, but gives direct links to the appropriate "Documentation" page for further reading.

I certainly don't want to steal @loudenhugely 's thunder, since they started this topic, but I'd love to hear what both of you (and anyone else) thinks of this feedback. I'm not a GitHub pro by any means, but I've forked the HA repo, so that I can mock up some changes I'd like to suggest at some point. I have a little bit of web design experience, so I'd like to contribute in any way that I can. I'm going to have to get my HA instance running smoothly first before I dive in fully, but I'm happy to keep this discussion alive.

[dannytsang]

I have started working on this and added 2 new pages:

1. Overview
2. Integration

If you could take a look and let me know what you think of the new Overview page where I have tried to describe key areas like integrations, devices & entities, add-ons, etc.

The other part I wanted to bring to your attention is the flow. I have added the overview page after the onboarding page because people should have a working Home Assistant and I thought it might be a good point to go over the terminology and concepts at that point but calling it "overview" seems odd. Here's an example what it looks like:

Ignore the integration page for now because I have moved the last part of the onboarding page for now.

[loudenhugely]

Hey! Thanks so much for taking my feedback to heart and trying to change things. On a macro level, I think the issue is that literally every page I’ve seen assumes I’m a coder. And that’s cool - it feels like coders’ solutions to home automation. But I’m a musician and got here bc of a friend. I Hate the idea of all my data going to Amazon et al and Love the whole self contained privacy bent to your work. But I might be in the wrong place! I’m slowly working through issues, but GitHub and Reddit are again the domain of coders and the weeds get Very thick Very quickly if you’re not. Again, that’s cool, as it’s y’all’s thing not mine - you’re under no obligation to help me fit in. And I do understand that open source means users also help in the making process, which I would love to do - I’m just not qualified! So I commented on the first two pages I landed on but then stopped, but you get the idea. Perhaps if y’all would like users who aren’t (yet) coders, you could have more documentation for us. I know it would be a pain! Specifically, if I tried to tell you all the things I don’t get, it’d be an even longer email! I’m not a technophobe or Luddite by any stretch - I even edited my autoexec.bat file back in the day! So it’s fun but it’s a slog. I will look at the pages you sent me on my computer - for some reason they just look like code on my phone. And I will try to give you more concrete suggestions if you want them. Thanks so much for reading all this!

Sent from my iPhone

On Jun 15, 2022, at 3:29 PM, Danny Tsang @.***> wrote:

 I have started working on this and added 2 new pages:

Overview Integration If you could take a look and let me know what you think of the new Overview page where I have tried to describe key areas like integrations, devices & entities, add-ons, etc.

The other part I wanted to bring to your attention is the flow. I have added the overview page after the onboarding page because people should have a working Home Assistant and I thought it might be a good point to go over the terminology and concepts at that point but calling it "overview" seems odd. Here's an example what it looks like:

Ignore the integration page for now because I have moved the last part of the onboarding page for now.

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.

[ndudde67]

I agree, Overview seems weird to be in the middle, but Integration then Automation seems perfect. Splitting the Onboarding page off into the Integrations page like you did is exactly how I think it should be, IMHO. Maybe Overview could be titled "Interface Overview" or "Interface Concepts Overview." Again, I think it is redundant to have the "Getting Started" page AND the sidebar navigation AND the menu at the top of the page, but that is really a secondary issue.

[dannytsang]

@loudenhugely Home Assistant is making it easier and easier and feedback like yours will hopefully make it easier for people to follow. The coder like mentally is historical so it I believe it is worth taking the feedback on-board.

Also I just fell into that same trap and linked some content that displays it like code because it is being treated as code. Sorry about that. I'm not sure if there's a way to show you a preview of the new page like it would appear on the site except attaching it as a screenshot so here it goes:

[dannytsang]

Thanks @ndudde67. I prefer working with the content and generally leave things like style and navigations to the pros like @frenck & co 😀

[dannytsang]

@ndudde67 I ended up with Concepts and terminology instead of having a heading with the word Overview. I've pushed the changes to the project. 🤞 there are no issues.

[ndudde67]

Sorry for the late reply. I've "approved" these changes, but AFAIK I don't have any real authority here (I'm pretty new) so if someone else can OK these changes, that would be swell. For anyone else that wants to see the changes in more visual format: https://deploy-preview-23127--home-assistant-docs.netlify.app/getting-started/index.html

[dannytsang]

Thanks @ndudde67 I have added scenes (as well as scripts) to it as well now. In order for the changes to be put into the documentation, it needs to be reviewed and approved by a maintainer. Given the nature of the change, I suspect it won't make it in until 2022.7 if there are no issues.

@loudenhugely hopefully you can preview the changes in @ndudde67 post above https://deploy-preview-23127--home-assistant-docs.netlify.app/getting-started/index.html but don't worry if not 😃

[github-actions[bot]]

There hasn't been any activity on this issue recently. Due to the high number of incoming GitHub notifications, we have to clean some of the old issues, as many of them have already been resolved. If this issue is still relevant, please let us know by leaving a comment 👍 This issue has now has been marked as stale and will be closed if no further activity occurs. Thank you for your contributions.