Missing documentation: Limitations and consequences of using a specific Device Class

[wentzel]

As a developer I would expect to find information in the documentation about how my choice of device class impacts my app.

Since issue #353 you have included documentation around some limitations of some device classes on https://apps.developer.homey.app/the-basics/devices/capabilities#device-indicators-and-custom-capabilities. However, I would hope that there is also some benefit of using the "correct" device class. However, currently I cannot find any documentation that tells me what those benefits might be.

Please note that even though the limitiations around setting the status indicator is the one I'm mentioning here, this is not the only limitation that I would like to see in the documentation. Whatever implication there is when choosing a specific device class would be beneficial to see in the documentations, since otherwise there is now way for me as a developer to understand how to best build my app.

Thus, I would suggest to further complete the documentation with information what each device class brings when it comes to possibilities and limitations. Perhaps it could be added as details for each device class on https://apps-sdk-v3.developer.homey.app/tutorial-device-classes.html and perhaps a more general description of the consequences of choosing a specific device class on https://apps.developer.homey.app/the-basics/devices#device-class.

[jeroenwienk]

I have improved the docs here https://apps.developer.homey.app/the-basics/devices#device-class. Let me know what you think.

[wentzel]

I have improved the docs here https://apps.developer.homey.app/the-basics/devices#device-class. Let me know what you think.

Great! I feel like the section now explains the general concept quite well! Personally, I would still really like to be able to see the specific benefits and limitations for each class. As it is now, there's general info on the page you updated, then there's the reference page with the list of all classes, and then there's the info around limitations of status indicators for some classes on yet another page.

For me (a beginner Homey developer) it gets quite difficult to grasp all the ifs and buts when it's so scattered. I'm used from other documentation to just be able to search for a class and then all the documentation regarding that class is right there. When and how to use it, What can and can't be done with that class, etc. For me, I think that would make it a lot easier to get an understanding of what possible and not.

[jeroenwienk]

I have improved the docs here https://apps.developer.homey.app/the-basics/devices#device-class. Let me know what you think.

Great! I feel like the section now explains the general concept quite well! Personally, I would still really like to be able to see the specific benefits and limitations for each class. As it is now, there's general info on the page you updated, then there's the reference page with the list of all classes, and then there's the info around limitations of status indicators for some classes on yet another page.

For me (a beginner Homey developer) it gets quite difficult to grasp all the ifs and buts when it's so scattered. I'm used from other documentation to just be able to search for a class and then all the documentation regarding that class is right there. When and how to use it, What can and can't be done with that class, etc. For me, I think that would make it a lot easier to get an understanding of what possible and not.

I think for now it's clear what the intention of the classes is. Documenting all cases would be alot of work which is not a high priority now. I have created a task to improve te classes docs in the future.