search

home-assistant / home-assistant.io

:blue_book: Home Assistant User documentation
https://www.home-assistant.io
Other
4.98k stars 7.29k forks source link

Information in this page is incomplete #22913

Closed snigehere closed 2 years ago

snigehere commented 2 years ago

Feedback

The page lists one paramater for the yaml but the text refers to other unlisted parameters .. It appears to be incomplete.

URL

https://www.home-assistant.io/integrations/sky_hub/

Version

2022.5.5

Additional information

No response

probot-home-assistant[bot] commented 2 years ago

Hey there @rogerselwyn, mind taking a look at this feedback as it has been labeled with an integration (sky_hub) you are listed as a code owner for? Thanks! (message by CodeOwnersMention)

RogerSelwyn commented 2 years ago

Please can you expand on what you think is missing and what section of text refers to more parameters.

snigehere commented 2 years ago

Hi Thanks for the quick response

So first I am fairly new to doing configuration updates in HA - up until recently I have just used UI based components. I really appreciate the time everyone puts supporting the solution.

The first step in the instruction was easy .. I added the detail to from the example then spotted that the host needed to be added .. It would have been helpful to include in the example as I believe sky routers typically come with 192.168.0.1 as the default now so most people would need to add it.

Having done the configuration I was unsure if I needed to restart or not - I know some changes to require it and others do not so I restarted anyway. It would really help to have step to validate it was working - eg "you should now see "xxxxx in yyyy" (a lot of the documentation in other areas could do with this as well so maybe its not a "standard" in documentation. My router is a sky Q router so I was unsure if it was supported or not so the validation would have really helped.

The next step sent me off to another page - "See the device tracker integration page for instructions how to configure the people to be tracked."

At the top of that page was a further example on the yaml configuration (for a netgear router) and that one had additional user and password parameters so I assumed I needed to include those but it seems not. This caused me some confusion for a while so with the link it might have been helpful to just say the password and userid parameters are not needed for the sky integration.

Looking back maybe I could have been more trusting of the process and documentation but so far I have had a lot of issues with documentation, posts and video's referring to things that have changed and no longer work that way .. maybe that's not core documentation but its hard to be sure. If documents had information such as when it was issued, last reviewed and related version of software that may assist but that, of course, is just general feedback and not at all related to your sky integration.

Thanks

Nigel

On Mon, 30 May 2022, 07:01 RogerSelwyn, @.***> wrote:

Please can you expand on what you think is missing and what section of text refers to more parameters.

— Reply to this email directly, view it on GitHub https://github.com/home-assistant/home-assistant.io/issues/22913#issuecomment-1140731497, or unsubscribe https://github.com/notifications/unsubscribe-auth/AZANJG5WZYF5SYZDUET75C3VMRKS7ANCNFSM5XIZ6ORA . You are receiving this because you authored the thread.Message ID: @.***>

RogerSelwyn commented 2 years ago

The first step in the instruction was easy .. I added the detail to from the example then spotted that the host needed to be added .. It would have been helpful to include in the example as I believe sky routers typically come with 192.168.0.1 as the default now so most people would need to add it.

The default is 192.168.1.254. I'm not sure why, because that was set well before I took the integration on. I can't change it without breaking existing installations. It does say on the page what the default is and there is an option to include the host. I know that it is HA core team, desire to only include the minimum in the example, hence the host isn't included.

Having done the configuration I was unsure if I needed to restart or not - I know some changes to require it and others do not so I restarted anyway.

Pretty much any YAML based change in HA needs a restart of some sort, though many of the more standard components now have reload capabilities available in the developer menu. To be honest this is a guide on how to use the integration, not how to use HA, so I don't intend to make any change in support of this.

It would really help to have step to validate it was working - eg "you should now see "xxxxx in yyyy" (a lot of the documentation in other areas could do with this as well so maybe its not a "standard" in documentation.

The linked device-tracker page I think provides reasonable detail on what you will find when setup properly for legacy device trackers, which is what this is.

My router is a sky Q router so I was unsure if it was supported or not so the validation would have really helped.

This is a good point. All I know is that it supports the Sky Q Hub, which is described as a 'Sky Hub' on its web page. I don't have any of the other models of Sky Router to validate whether they are or aren't supported by the integration. As I have commented before elsewhere, this integration is a screen scraper, and I'm not sure if all Sky Routers look the same to this integration and will therefore work. So if I add a statement to say it only Sky Q Hub that may be as much a lie, as saying it supports the 'Sky Hub' or 'Sky Broadband Hub'.

I'm happy take view on this as to what is the right approach to take.

The next step sent me off to another page - "See the device tracker integration page for instructions how to configure the people to be tracked." At the top of that page was a further example on the yaml configuration (for a netgear router) and that one had additional user and password parameters so I assumed I needed to include those but it seems not. This caused me some confusion for a while so with the link it might have been helpful to just say the password and userid parameters are not needed for the sky integration.

The integration documentation pages provide details on all the mandatory parameters (i.e. just the sky_hub platform element), if userid and password were required/mandatory they would have been listed as such. It might be worth raising a point against the Device Tracker integration to highlight that the example given there perhaps provides too much info. That said, userid and password whilst shown in the device_tracker page are not shown in the options on either the Device Tracker page or the Sky Hub page

Looking back maybe I could have been more trusting of the process and documentation but so far I have had a lot of issues with documentation, posts and video's referring to things that have changed and no longer work that way .. maybe that's not core documentation but its hard to be sure. If documents had information such as when it was issued, last reviewed and related version of software that may assist but that, of course, is just general feedback and not at all related to your sky integration.

I think that HA as it currently stands is still designed for a fairly technical audience who don't typically need everything described. I'd also agree that because of the relatively rapid evolution of the HA platform that documentation gets out of date. That said, there is a huge amount of documentation and developer support for the platform, far more than I've found on any other that I've been involved with (and I've done a few). I think you are just going through the beginning hurdles that you will find with any new, complex, tool that you get involved with. Give it a month and you'll be writing your own.

snigehere commented 2 years ago

Thanks for the detailed response.. I was not suggesting to change the default of the host but to simply add the host parameter to the example as most people need it.I note its shown on the example on the device integration page.I have said my piece and you have responded .. as the owner you can accept or reject any feedback as you see fit.I guess all my time spent trying to make things work is a learning experienceThanks for your time..Best RegardsNigel Wheatley1 Orkney Road, Portsmouth, PO6 3UETelephone +44 (0)23 9221 5040Privacy Statement:If you are a private individual you may not pass my personal details, including my email address,to any company, or register, record or display it on any web site without my explicit authority.If you are a company or organisation you may not use my personal details,including my email address, beyond the scope of this transaction.To do so would be a breach of my data privacy. -------- Original message --------From: RogerSelwyn @.> Date: 30/05/2022 15:18 (GMT+00:00) To: "home-assistant/home-assistant.io" @.> Cc: snigehere @.>, Author @.> Subject: Re: [home-assistant/home-assistant.io] Information in this page is incomplete (Issue #22913)

The first step in the instruction was easy .. I added the detail to from the example then spotted that the host needed to be added .. It would have been helpful to include in the example as I believe sky routers typically come with 192.168.0.1 as the default now so most people would need to add it.

The default is 192.168.1.254. I'm not sure why, because that was set well before I took the integration on. I can't change it without breaking existing installations. It does say on the page what the default is and there is an option to include the host. I know that it is HA core team, desire to only include the minimum in the example, hence the host isn't included.

Having done the configuration I was unsure if I needed to restart or not - I know some changes to require it and others do not so I restarted anyway.

Pretty much any YAML based change in HA needs a restart of some sort, though many of the more standard components now have reload capabilities available in the developer menu. To be honest this is a guide on how to use the integration, not how to use HA, so I don't intend to make any change in support of this.

It would really help to have step to validate it was working - eg "you should now see "xxxxx in yyyy" (a lot of the documentation in other areas could do with this as well so maybe its not a "standard" in documentation.

The linked device-tracker page I think provides reasonable detail on what you will find when setup properly for legacy device trackers, which is what this is.

My router is a sky Q router so I was unsure if it was supported or not so the validation would have really helped.

This is a good point. All I know is that it supports the Sky Q Hub, which is described as a 'Sky Hub' on its web page. I don't have any of the other models of Sky Router to validate whether they are or aren't supported by the integration. As I have commented before elsewhere, this integration is a screen scraper, and I'm not sure if all Sky Routers look the same to this integration and will therefore work. So if I add a statement to say it only Sky Q Hub that may be as much a lie, as saying it supports the 'Sky Hub' or 'Sky Broadband Hub'. I'm happy take view on this as to what is the right approach to take.

The next step sent me off to another page - "See the device tracker integration page for instructions how to configure the people to be tracked." At the top of that page was a further example on the yaml configuration (for a netgear router) and that one had additional user and password parameters so I assumed I needed to include those but it seems not. This caused me some confusion for a while so with the link it might have been helpful to just say the password and userid parameters are not needed for the sky integration.

The integration documentation pages provide details on all the mandatory parameters (i.e. just the sky_hub platform element), if userid and password were required/mandatory they would have been listed as such. It might be worth raising a point against the Device Tracker integration to highlight that the example given there perhaps provides too much info. That said, userid and password whilst shown in the device_tracker page are not shown in the options on either the Device Tracker page or the Sky Hub page

Looking back maybe I could have been more trusting of the process and documentation but so far I have had a lot of issues with documentation, posts and video's referring to things that have changed and no longer work that way .. maybe that's not core documentation but its hard to be sure. If documents had information such as when it was issued, last reviewed and related version of software that may assist but that, of course, is just general feedback and not at all related to your sky integration.

I think that HA as it currently stands is still designed for a fairly technical audience who don't typically need everything described. I'd also agree that because of the relatively rapid evolution of the HA platform that documentation gets out of date. That said, there is a huge amount of documentation and developer support for the platform, far more than I've found on any other that I've been involved with (and I've done a few). I think you are just going through the beginning hurdles that you will find with any new, complex, tool that you get involved with. Give it a month and you'll be writing your own.

—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you authored the thread.Message ID: @.***>