I'd like to propose that, immediately following the 2.2.5 release, Hubitat have a "Day of Documentation" (or, even better, Documentation Week) to fix and supplement the online documentation. The idea is to have a short period of concerted effort by Hubitat and interested developers to fix, complete, and supplement the Developer documentation. For a product that depends on a developer community, complete documentation is a huge step in supporting developer efforts (and reducing the time that staff spends answering question!).
There are many pages that have gone missing (State object, Command Object, Mode Object, others?), and huge "to be done later" sections that just haven't gotten done. These could all be fixed.
I realize the documentation concept is supposed to be one where developers can contribute to the documentation via the wiki. But users / developers are often not in a position to do that (I can't properly contribute to what I don't fully understand). In any case, the moderation process for user contributions appears to be stalled -- months ago, I spent time editing the Capabilities page (adding "unit" information, adding a section on "Implementation notes", etc.), but it never got incorporated and the edits now seem to have disappeared from my pending edits without any response from a moderator. I'd be willing to give another try at this as part of a concerted effort to fix the full set of documents.
If Hubitat shows interest, I'd volunteer to contribute to at least the Capabilities page by adding information on the proper "Units" to include in SendEvent messages and to the "State Object" page -- I recently learned a lot from the staff about how this object works and particular race conditions that need to be considered when writing to the state. It would be helpful to have a set of "Implementation Notes and Cautions" on these pages to centralize relevant knowledge that is now sprawled about the forums.
Would the folks at Hubitat ever consider some sort of "Volunteer Documenter" program? I've got a few apps and drivers I want to develop, but the Hubitat-provided developer docs seem...pretty incomplete.
Is there any way that some of us could be granted read-only access to parts of the underlying Hubitat codebase in order to help them document it on a volunteer basis? That sounds like a security nightmare even to me, but I'd really like to have access to better documentation myself and would love to help create it in some way.
Alternatively, any way we could help fund improved developer docs? I'd contribute to a Kickstarter that would get me better docs on developing drivers and apps for Hubitat.
I had previously started this thread, but I've given up on this issue for now.
As a start, I'll say that the Hubitat staff are great about answering questions and providing clarifications on the user forums. The unfortunate part is that their answers /clarifications generally don't make their way back into the documentation in any structured way. You can sometimes find what you are interested in by searching the forums, but that can be hit-or-miss.
The developer documentation is in a Wiki form, so, in theory, anyone can submit edits. But in reality, the volunteer model doesn't work as there seems to be two main problems (1) end-users who need the help and find gaps in the documentation, don't know enough to do the edits; (2) end-user's who know enough to do the edits, don't have the motivation to do so.
Hubitat continues to add key features to the product, and a small company has to pick their priorities. Right now, their priority seems to be adding features and platform functionality. That seems a reasonable choice. At some point I hope to see them provide more complete documentation -- its likely a time-saver in the long run so they don't have to answer as many forum questions, but I suspect we'll all be waiting a while for that.
All that makes sense! Right now I'm in the "don't know enough to make the edits" stage, fumbling my way through trying to learn stuff.
I think another part is that, honestly, it never would have occurred to me to edit the wiki if you hadn't mentioned it. I'm coming to this from enough of a software dev perspective that the idea of an end user documenting an API by discovery is insane at first glance.
Now that you've brought it up, though, as I play with Hubitat more I'll try to start adding things to the wiki when they seem helpful, even when they're not as "complete" as I would want API documentation to be.
Maybe something that would be helpful is a standardized way of marking up on the Wiki those bits that are provided by Hubitat and those bits that are provided by the community? I know the wiki itself will show some amount of authorship but I'm new to wiki editing so I'm not sure how obvious that kind of thing is.
