No prominent pairing instructions

[toddjonker]

Feedback

I'm attempting to pair a new device after not doing so in a while, and I don't remember the process. I would expect this page to have prominent pairing instructions, but I can't find anything. Yeah there's troubleshooting, but what about the basics?

URL

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

Version

2025.2.1

Additional information

No response

[home-assistant]

Hey there @dmulcahey, @Adminiuga, @puddly, @TheJulianJES, mind taking a look at this feedback as it has been labeled with an integration (zha) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of zha can trigger bot actions by commenting:

• @home-assistant close Closes the feedback.
• @home-assistant rename Awesome new title Renames the feedback.
• @home-assistant reopen Reopen the feedback.
• @home-assistant unassign zha Removes the current integration label and assignees on the feedback, add the integration domain after the command.
• @home-assistant add-label needs-more-information Add a label (needs-more-information) to the feedback.
• @home-assistant remove-label needs-more-information Remove a label (needs-more-information) on the feedback.

[puddly]

There is a section about adding devices to your network: https://www.home-assistant.io/integrations/zha/#adding-devices

[kylehakala]

Just stopping by! I've been sitting off to the side for a while now mulling over some reorganization to the existing docs (some cleanup/editing, re-structuring, etc) to make for a better user experience, both first-time and returning users. I'm hoping to get some more time this week to keep on improving this page more (assuming my PR #37407 is accepted of course).

Tons of great info on the page! I agree with you 100% nevertheless. It has been difficult for me to navigate. I think moving some of the device info tables to the end of the page as "Appendix style" reference data (moving the more common Home Assistant specific docs that people are familiar with being closer to the top) could help improve the page layout.

[Hedda]

FYI, create a pull request adding some specific info I thought was missing in the process for pairing/joining Zigbee devices to ZHA:

• Update zha.markdown adding Zigbee devices steps #37944

[kylehakala]

I've made a couple modifications recently that bump the "Adding devices" docs further up, right after "Configuration" so that it is easier to jump right into that.

No specific content was changed, but I will continue refining that over the next couple weeks.

[Hedda]

Feel free to review and give feedback with improvement suggestions on this draft:

• Update zha.markdown adding Zigbee devices steps #37944