Update zha.markdown with intro to the ZHA integration and Zigbee #12064
Conversation
…eneral Update current zha.markdown with more introductory information which describes the purpose of this ZHA integration/component, the Zigbee concept in general, basic Zigbee troubleshooting, as well as some links ((with short descriptions) to a few related projects and other directly relative integrations. I also included a couple of general benefits arguments to compare the ZHA integration with other solutions for getting Zigbee devices into Home Assistant, but without in any way trying to put down the other possible solutions for gettings Zigbee devices into Home Assistant. In my opinion, all this text in this pull request gives a better introduction to the ZHA integration for those who are either new to Zigbee or those who know about Zigbee but are new to Home Assistant and might be looking as other solutions to replace their current way of controlling Zigbee devices. Credit to much of this information goes to this blog post by Tinkerer as well as the contributors to the Zigbee2mqtt.io website who I think have done a great job at describing the benefits of different Zigbee implementations that may not be clear to users without this information if you are either new to Zigbee or new to Home Assistant. For reference see: - https://blog.ceard.tech/2019/11/zigbee-and-home-assistant.html - https://www.zigbee2mqtt.io/ - https://github.com/ioBroker/ioBroker.zigbee/blob/master/README.md
|
Sorry I did not notice that Grammarly must have auto-corrected the spelling of "Home Assistant". Fixed. |
Update zha.markdown with the correct spelling of "Home Assistant". Did not see that Grammarly must have auto-corrected that spelling.
|
Merge conflicts between our main branches, is something we release and is not something you have to worry about. Besides that the build currently fails, I do think this PR is out of control a bit. While there is definitely useful information in here, it is way too big of n introduction. This page should be short and to the point on how to configure and setup the integration. With this change is becomes quite big and misses that goal. Furthermore, it contains tons of technical things. For example, for Home Assistant user's end documentation, the part on zigpy isn't really adding anything. Furthermore, this page should not be about "Zigbee", but about ZHA. I think we should not merge this. |
|
@frenck My main issue with the current documentation surrounding Zigbee support in Home Assistant is the same that I think @DubhAd (a.k.a. Tinkerer) tries to explain in his blog post, which is why he summarizes a few popular methods of connecting Zigbee devices to Home Assistant, including a summary of their advantages as well as give a short introduction to Zigbee itself: https://blog.ceard.tech/2019/11/zigbee-and-home-assistant.html @Adminiuga & @dmulcahey If this PR is not acceptable then a few follow-up questions are;
I mean, if you are new to Home Assistant then where is it described/documented for end-users the fact that Zigbee devices can be connected to Home Assistant in a lot of different ways? That is, how should someone new to Home Assistant get that information from the Home Assistant website official without resorting to posting it as a question on the community forums? If you disregard the fact that you can indirectly connect Zigbee devices via a multitude of proprietary gateways/bridges/hubs (like example Philips Hue Bridge or IKEA Tradfri Gateway) the answer you usually do get if you post in the community forums today at least these four (4) different non-proprietary ways of connecting Zigbee devices to Home Assistant which makes it very confusing:
I understand that it might be hard for developers or advanced users who worked with Home Assistant for years, but as someone who is a technical person but relatively new as a Home Assistant let me tell you that getting started with Home Assistant is still not easy or a straight path and that goes especially for Zigbee. |
|
The problem you are trying to solve right now, is educating people on Zigbee. Which is fine, and I agree we should cover it, but not on the integration page. We currently do not have a fitting location for that. 2 previous PR's with an attempt to add that have been closed as well. The reasoning is that we are currently in the planning and preparation of restructuring, some is already visible, most is still to come. |
|
@frenck I see your point and I agree. But I also agree with Gamester (btw thanks for all your contributions). I do remember my first days with HomeAssistant and trying to get ZHA running. I did not find ZHA documentation particularly helpful. So assuming the premises of "This page should be short and to the point on how to configure and setup the integration" what are our options for:
|
|
We do have options on the integration page, I just stated the integration page is not about writing an introduction of manual about Furthermore, this drifts towards a comprehensive guide on Zigbee and options, which this page is not about. This page is about the ZHA integration. That is its subject. From the OP, and not fitting here:
|
|
yeah, ZHA integration page is a tad out of control. Yet at the same time i'd say all the information there is needed, we just have to structure it better. Can integration pages have subpages? |
Nope, that freaks out Jekyll at this point. Jekyll only handle 1 level in a collection (which integrations are). This is one of the reasons for the many Markdown changes lately, to allow us to make the Markdown more portable and look into other solutions. |
|
bummer :( |
|
Yes I agree that is the ZHA integration page do more and more drift towards a comprehensive guide about this ZHA implementation. but like it or not I think still think that it is for good reason as the information is needed because as far as I can tell there is currently nowhere else on the official Home Assistant website to contain 'usage' information about specific implementations. I think that it should be noted that the ZHA component implementation is not like most other integrations for Home Assistant from an end-user point-of-view, it like the Z-Ware integration is a bit special as adds built-in native Zigbee hub functionality to Home Assistant own user-interface instead of just integrating with a third-party hub which in turn acts as a gateway or bridge by handling all the device connections and configuration separately in its own proprietary interface. So at least end-user point-of-view it could be argued that is ZHA component implementation is not just an integration with any third-party system (hubs/gateways/bridges) which has its own user-interface, as the ZHA component does not have its own user-interface at all and instead adds fully built-in Zigbee hub function inside Home Assistant itself. It can as such not simply be compared to other integrations, (with the exception of the current Z-Wave component implementation for Home Assistant). It is because of this that I think that the Home Assistant core team should seriously reconsider the need to keep all documentation for both end-users and developers about the ZHA component on the official Home Assistant website, not only for getting the first-day operation like started but also for second-pay operations like general usage, including A-Z configurations, settings, and troubleshooting. In my opinion, even new developers who stumble onto ZHA should also be presented with an introduction to ZHA from a development point-of-view and preferable even more development documentation that is specific ZHA. Again, as this ZHA component do not just integrate with a third-party system that has its own interface but instead once installed fully integrates into Home Assistant itself. |
|
You are running around in circles now, and I am not playing that game. We are not accepting this PR as reasoned before. Feel free to open a PR that does meet the requested changes. Thanks. 👍 |
|
@balloob Can we please get your or someone else input some constructive feedback here as well? @frenck I kind of understand your frustration with my OCD behaviour here but I also think that your action of just closing a PR and ignoring comments from your community is very unprofessional. I'm speaking from personal experience as for over 10-years I was a project manager for XBMC / Kodi, during which time our community lost many great developers because some people lack of people skills. Actions like that risk creating a hostile environment which can in worst case alienating your whole community or at best risk alienating one or more developers which in the long run can make the whole community lose out of their future contributions. My tip to you, if you get annoyed at people (like myself here) then instead of displaying authority and just cur that person off, it always better to just to excuse yourself, step away and ask someone else with more patience to take over that discussion instead. |
|
There is no need to tag people, this was already internally discussed with balloob.
Sorry to hear you feel that way, I commented extensively above and provided reasoning. I don't feel like that is called for. We are still happy to accept changes, within the scope plotted out above. |
|
Sure that you already considered it before but having an official wiki would solve much of these issues. Again speaking from experience as I previously worked a lot with Kodi/XBMC wiki https://kodi.wiki |
|
We are well aware of the issues we have with our documentation and are working in solutions. Thanks! |
Proposed change
Update current zha.markdown with more introductory information which tries to describes the purpose of this ZHA integration/component, the Zigbee concept in general, basic Zigbee troubleshooting, as well as some links ((with short descriptions) to a few related projects and other directly relative integrations.
I also included a couple of general benefits arguments to compare the ZHA integration with other solutions for getting Zigbee devices into Home Assistant, but without in any way trying to put down the other possible solutions for gettings Zigbee devices into Home Assistant. Hopefully, this will give new end-users and new developers a better idea of what to expect and maybe more reasons to try it out.
In my opinion, all this introduction text in this pull request should end-users who are curious about Zigbee in Home Assistant a better understanding of what the ZHA integration does, as it is especially meant for those who are either new to Zigbee or those who know about Zigbee but are new to Home Assistant and might be looking as other solutions to replace their current way of controlling Zigbee devices.
Credit to much of this introduction information goes to this blog post by @DubhAd (a.k.a. Tinkerer) as well as the contributors to the Zigbee2mqtt.io website who I think have done a great job at describing the benefits of different Zigbee implementations in their introduction on their websites that may not be clear to users without this information if you are either new to Zigbee or new to Home Assistant.
For reference please see (at least read the first link below to blog-post by @DubhAd a.k.a. Tinkerer):
https://blog.ceard.tech/2019/11/zigbee-and-home-assistant.html
https://www.zigbee2mqtt.io/
https://github.com/ioBroker/ioBroker.zigbee/blob/master/README.md
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.