Update and improve introduction in zha.markdown #28869
Conversation
Improve ZHA introduction in zha.markdown
Incorrect usage of the terminology term: “backwards compatible”, use “backward compatible” instead.
There was a problem hiding this comment.
Thanks!
Could you make the changes a bit more compact? There are many phrases that incorporate too much jargon and can often times be entirely removed without changing any meaning:
- "Zigbee Coordinator radio adapter or hardware module"
- "physical radio adapter"
- "from an end-user's point-of-view"
Specification revisions and acronyms are a little too techincal for an introduction so let's keep it as simple as possible.
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
Rewrote to remove some jargon
@puddly Tried to get it more compact, by at least removing most technical jargon + acronyms, and splitting only sections. |
|
@puddly I have tried to make all requested changes so wondering if there is any chance to get this reviewed again? |
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
There was a problem hiding this comment.
Keep in mind that this documentation is for the ZHA integration, not for Zigbee in general!
Let's focus on paring down the documentation. Right now, it's so long and dense that a typical user of Home Assistant can't just open it up and look at it without being overwhelmed. We don't need to cover every use case and every possible question someone can possibly have about Zigbee in the documentation.
Right now, we don't have a place for in-depth Zigbee documentation like this. Perhaps you can instead extend the Zigpy wiki and we then migrate the content in the future to a generated documentation website?
Update introduction based on feedback.
OK, I now tried restructuring and rewritten the introduction section based on that feedback while keeping "must have" info. |
Proposed change
Updated and improved the ZHA integration introduction section (including adding a couple of links to other sections in this ZHA documentation that IMHO isalso very important for beginners to read and be aware of).
Since the ZHA integration userbase/usage increased (possibly due to SkyConnect/Yellow + other factors) we see more and more new users of the ZHA integration now posting in Home Assistant's community forum every day asking for help soon after they run into common setup or environment issues when getting started with the ZHA integration and Zigbee.
I think most of those issues occur because many of those new users did not understand the basic Zigbee fundamentals and limitations that for for better or worse users should really need to know before the begin creating a new Zigbee network and start simply adding any Zigbee devices located anywhere in their home to the ZHA integration.
I believe this improved introduction could help many new users avoid most of those basic issues or common pitfalls for Zigbee, and hopefully, they will get a better out-of-the-box user experience from the very beginning and not early in their Zigbee adoption have to go into delving deeper into Zigbee troubleshooting to correct simple setup mistakes that are caused by common Zigbee limitations.
For example; new users are not aware that they must add many Zigbee Router devices to get any kind of decent range and coverage, epecially before they start adding Zigbee End Devices.
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.