Create zigbee.markdown as start of Zigbee documentation

[Hedda]

Description:

Creating zigbee.markdown as a start of a ZHA documentation even if it is almost only a placeholder.

The base of this Zigbee text was mainly copied from the Z-Wave documentation for Home Assistant.

My purpose of this is to at least get some information about the existing Zigbee Home Automation integration into the main documentation as I think that this could be used as a base and a start for other technical writers who can build on this and help improve the Zigbee documentation for Home Assistant.

With this, I also wish to expose the existing Zigbee Home Assistant integration and show it in the same light as the existing Z-Wave integration. I hope that this will help the existing Zigbee Home Assistant integration become more of a first-class citizen in Home Assistant, just like the existing Z-Wave integration already is.

Ping @dmulcahey @Adminiuga & @damarco for feedback request on this documentation content.

PS: This PR is for the 'current' branch and replaces #10582 which was based on the 'next' branch.

Checklist:

• Branch: next is for changes and new documentation that will go public with the next Home Assistant release. Fixes, changes and adjustments for the current release should be created against current.
• The documentation follows the standards.

[frenck]

My initial thought with this is: We should not do this.

Reason for this is:

• Z-Wave docs are scattered around the site and that makes it hard for the user to find things.
• We have integration documentation for these things.
• ZHA is not the only Zigbee solution, which is ignored in this PR.

I think this is just a little too soon. We should definitely revisit parts of the website & documentation, which should start at revisiting our general documentation and website structure.

From that point of view, I don't think Z-Wave or Zigbee is a first-class citizen for the website, "Protocols": maybe.

[Hedda]

@frenck last section covers some non-native alternative ways of controlling Zigbee devices from HA.

"Other than using the above described native Zigbee Home Automation integration in Home Assistant, there are also other integrations for Home Assistant connect a third-party bridge, hub or gateway (that can be hardware or software) which in turn can also communicate with Zigbee devices, through those other integrations mostley or fully absract the fact that the devices are using the Zigbee specification (as such that the devices could just as well be using any other specification). Such integrations with third-party bridges, hubs and gateways that can also communicate with Zigbee devices include but are not exclusive to; deCONZ, Zigbee2mqtt, Philips Hue Hub, Ikea Tradfri Gateway, Osram Lightify, and Samsung SmartThings Hub."

You could directly compare this to the fact that it is as far as I could see no mentions in the Z-Wave documentation that controlling Z-Wave devices is also possible through non-native integration with third-party bridges, hubs and gateways. Therefore this Zigbee documentation is possibly fairer by at least listing other options.

...though see now that I drive that point further could have also listed the Wink Hub 2 as the Wink integration is another third-party bridge/hub/gateway solution that abstracts Zigbee and Z-Wave devices. Point is that none of those other integrations let you connect a Zigbee USB stick to a computer running Home Assistant, which is what in my options makes the Zigbee Home Automation integration comparable to the existing Z-Wave integration in Home Assistant, and is why I feel that it deserves to be documented and highlighted on Home Assistant website in the same way as Z-Wave currently already is.

Anyway, going from https://www.home-assistant.io/docs/ Z-Wave looks like a first-class on HA website.

[frenck]

You are missing my point. The point is that the current structure (including Z-Wave) is not good IMHO. That is why I don't feel like we should extend that in that way.

This has nothing to do with any class of citizenship.

[fabaff]

I'm with @frenck on this. We should review the structure first.

A while back we decided to move Z-Wave and MQTT away from the integration documentation to the "Docs" section. The reason was that both integration provided a huge amount of details which made the integration documentation a pain to read. Also, it was confusing for users to see that much information which was not relevant for their use case.

[frenck]

Thanks for providing the second opinion on this matter, fabaff.

So I'm going to close this, for now, let's revisit this in the future. Nevertheless, @Hedda, thank you for your contribution! That is appreciated.