HA documentation is poor beyond belief

[kevintedder]

Feedback

As an IT professional of 40+ years I am shocked at how poor the documentation for this software is. I've been struggling to use HA for over 2 weeks.

To highlight just one instance, as there are too many to list here, the Zigbee Home Automation page offers the following "help". CONFIGURATION VARIABLES database_path string REQUIRED Full path to the database which will keep persistent network data.

enable_quirks boolean (optional, default: true) Enable quirks mode for devices where manufacturers didn’t follow specs.

custom_quirks_path string (optional) Full path to a directory containing custom quirk modules that will take precedence over any built-in quirks matching a device.

In the configuration.yaml file I tried: zha: custom_quirks_path: '/root/config/custom_components/zha-device-handlers' The 'check configuration' says : Invalid config for [zha]: not a directory for dictionary value @ data['zha']['custom_quirks_path']. Got '/root/config/custom_components/zha-device-handlers'. (See /config/configuration.yaml, line 12).

I tried: custom_quirks_path: '/root/config/custom_components/zha-device-handlers' The 'check configuration' says : Integration error: custom_quirks_path - Integration 'custom_quirks_path' not found.

So just what format will work? If at all?

There are too many examples to list here of how inadequate this documentation is. It leaves out vital info that I have had to search the internet for. How anyone can say that HA is easy to use is beyond me.

Please provide working examples of the YAML files that actually do work.

URL

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

Version

2022.4.6

Additional information

No response

[probot-home-assistant[bot]]

Hey there @dmulcahey, @adminiuga, 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! _{^{(message by CodeOwnersMention)}}

[Adminiuga]

The configuration file uses yaml and you are not using any formatting so it's hard to say what you are doing wrong.

But if you are just starting with zha, it is unlikely you should be using custom_quirks_path option or any configuration options at all.

[kevintedder]

@Adminiuga Please let me state where I am with HA.

I started with HA installed and running on a RPI3B with 2 TUYA TRV's registered on the Tuya Smartlife app and sync'd up to my TUYA Cloud account. The HA TUYA integration can now see these devices and control them.

I now wish to use ZHA locally as the response times, via the cloud, are slow (2-3secs) and it relies upon my broadband.

I've installed ZHA with the ConBee II USB coordinator. It auto discovers the TUYA TRV's but they show up as 'OFFLINE' and with only 2 entities (basic_lqi & basic_rssi). I assume that this is because the device signature (below) is not being recognised correctly. ====BEGIN==== { "node_descriptor": "NodeDescriptor(logical_type=<LogicalType.EndDevice: 2>, complex_descriptor_available=0, user_descriptor_available=0, reserved=0, aps_flags=0, frequency_band=<FrequencyBand.Freq2400MHz: 8>, mac_capability_flags=<MACCapabilityFlags.AllocateAddress: 128>, manufacturer_code=4098, maximum_buffer_size=82, maximum_incoming_transfer_size=82, server_mask=11264, maximum_outgoing_transfer_size=82, descriptor_capability_field=<DescriptorCapability.NONE: 0>, *allocate_address=True, *is_alternate_pan_coordinator=False, *is_coordinator=False, *is_end_device=True, *is_full_function_device=False, *is_mains_powered=False, *is_receiver_on_when_idle=False, *is_router=False, *is_security_capable=False)", "endpoints": { "1": { "profile_id": 260, "device_type": "0x0051", "in_clusters": [ "0x0000", "0x0004", "0x0005", "0xef00" ], "out_clusters": [ "0x000a", "0x0019" ] } }, "manufacturer": "_TZE200_lllliz3p", "model": "TS0601", "class": "zigpy.device.Device" } ====END====

Having discovered the zha-device-handlers on Github, I assumed that this would solve my problem. However, the README file is not clear as to how to install and use it. Would a simple 'git clone' work? There is some description about setting up a development, but I only wish to use it, not create new ones.

Now I see that the 'custom_quirks_path' maybe the answer as to how to use this zha-device-handlers. But, as describe above, I do not understand how to implement it in the configuration.yaml file as there is no working example of the entries that are required in the YMAL file.

None of this documentation really helps in describing just how I am meant to configure the system to make it work. To date, much of it has been guess work from watching YouTube videos or reading about other peoples experiences. So the documentation fails in its objective to provide sufficient information to build a working system.

Please help me before I go bald from pulling out my hair.

[FrnchFrgg]

@kevintedder Note that Home Assistant already ships with the zha quirks. That custom quirks path is used when you want to develop or modify the quirks, or maybe install some bleeding edge version of the quirks in your HA. As for the documentation quality, there are obvious problems, but mind that documenting how every and all device is supposed to work will never be doable due to the sheer amount of them. Mostly, ZHA devices should either just work or need developer action (in the form of quirks), and in both cases the documentation is, although desirable, not first priority. Feel free to dive in and improve the end-user documentation. The developer-oriented one is probably supposed to go to https://developers.home-assistant.io/

[Hedda]

@kevintedder Most of your questions are better asked in other communication channels meant for community help/support, see:

https://www.home-assistant.io/help/

Foremost the community's forum for help/support, or Discord Chat Server for general Home Assistant discussions and questions:

https://community.home-assistant.io

and

https://discord.gg/c5DvZ4e

General tip before asking for help/support in such a community for an free and open-source project like this is to read/follow this:

http://www.catb.org/~esr/faqs/smart-questions.html

Note that Home Assistant already ships with the zha quirks. That custom quirks path is used when you want to develop or modify the quirks, or maybe install some bleeding edge version of the quirks in your HA.

That is correct, the "ZHA Device Handlers" library (a.k.a. zha-quirks) always gets installed by default with Home Assistant. All device types/models have unique device identifiers and if someone has already written a "quirk" (ZHA Device Handler) for a specific device and that quirk has been merged into the "ZHA Device Handlers" repository on GitHub then that will sooner or later be part of a release that will be updated in Home Assistant by the ZHA developers as a part of a dependency bump. If someone has written a new "quirk" or updated it and that has not yet been merged into the "ZHA Device Handlers" repository on GitHub then the users who own that device have the option to install that themselves manually using the mentioned custom quirk directly. Maybe that is what is somehow needed to be clarified in the ZHA integration documentation? Perhaps move the custom_quirks_path configuration example to -> https://www.home-assistant.io/integrations/zha#zha-exception-and-deviation-handling ?

As an IT professional of 40+ years I am shocked at how poor the documentation for this software is.

I am an IT professional since over 20+ years myself, however having had a lot of experience both using and gettting support as well as contributing to free and open-source projects to others myself, so I know that documentation for free and open-source projects made by volunteers can not be compared to the documentation produced by commercial IT companies who employ professional technical writers, but you have to respect that not paying for the product in any way you have no real right to just complain about inadequate documentation not suitable for new end-users getting from scratch with no previous advanced experience of configuring Home Assistant YAML files. Instead, try to approach this with more of an altruistic attitude like how can you help improve this documentation with your experience to help other beginners just getting started, either with more constructive feedback or by contributing written change suggestions.

That is, you first have to understand that Home Assistant is not a commercial product that has paid technical writers that write with the help of professional usability experts the most company has. Home Assistant is a free and open-source project and usually other than the initial documentation normally committed by the original developer of integration (commonly coded for free in their spare time), most of the end-user documentation is written by volunteering hobbyists who contribute by submitting pull requests to this documentation files in order to try help adjust missing or incorrect information and add readability improvements for others.

While I sincerely agree that the existing documentation is lacking the quality or quantity required and is insufficient for a purpose, I do not agree with your approach of harshly demanding improvements here instead of more humbly suggesting constructive feedback on exactly how to improve the documentation, or better yet, may I suggest that you try instead go a different route by first posting in the Home Assistant community forums with separate new topics on specific issues you want help (as that channel is better oriented towards getting assistance with questions or problems) and only then if you like to contribute back, assist other end-users of this project by submitting pull requests to this documentation files yourself.

PS: My own feedback to the project founders/owners/members would be to both allow more extensive end-user documentation for integrations as well as try to expedite and streamline the processing of submitted pull requests for documentation changes.

[github-actions[bot]]

There hasn't been any activity on this issue recently. Due to the high number of incoming GitHub notifications, we have to clean some of the old issues, as many of them have already been resolved. If this issue is still relevant, please let us know by leaving a comment 👍 This issue has now has been marked as stale and will be closed if no further activity occurs. Thank you for your contributions.