Proper Hubitat Elevation documentation in dire need

[maffpt]

Hi everyone,

Far from creating a turmoil among the community and Hubitat itself, I'd like to propose that we, developers, if it has not been done before, kind of demand from Hubitat to provide proper developer documentation.

On October/2018 was announced a new home for HE documentation (Hubitat Elevation Documentation Wiki Announcement), but it is, IMHO, insufficient in terms of developer needs. I frequently have to search for SmartThings documentation to find out how to do things, and I think it is a far from ideal situation.

As an example of insufficient documentation, I took a snapshot of one page of the documentation wiki:

Honestly, can a newbie easily understand what is a HubAction object? Maybe looking at the parameters it's possible to infer the purpose of a HubAction object. Infer ... that's not good, don't you all agree?

I know that every language/environment has its own learning curve - some with a soft slope, some steep one. However, I've never found an environment with a learning curve so steep that it looks like the Everest! The community is a great help - thanks, sherpas, I mean, guys! - but sometimes I see similar questions asked repeatedly, mostly because of lacking of proper documentation from Hubitat.

I know that it could be a community and Hubitat joint endeavour. Today we see that collaboration is a powerful tool, a win-win situation. However, in this specific case I have some points against it:

1. Consistency: it's prone to lack of consistency, since different people has different writing styles, different backgrounds, and some, as in my case since English is not my mother language, sometimes it can compromise the quality of the text;

2. Comprehensiveness: I believe that it's difficult to create a comprehensive documentation from the developers' side; sometimes we can infer from our experience (here we are again, infer ...) what the to be documented item do and not know deeply what it do;

3. Ownership: HE is a Hubitat's product. Hubitat profits from it and from our work. Not that profiting it is a bad thing, no, it's not. I'm sure that the community agrees that we want that Hubitat thrives and gets stronger and stronger and gets even more market share. We also have a huge investment here, and we want to "profit" from this investment using HE for a long time. However, if Hubitat presents us a comprehensive developers documentation, everybody wins: we, who could be more productive in our developments, and Hubitat, since we enrich their powerful platform with our developments. Win-Win!

Well, that's the idea ... I'd like to hear from the community.

Peace and health for everybody.

[bertabcd1234]

I definitely think this is a good idea, and Hubitat's current developer docs are clearly lacking. However, to be fair, they do not bill themselves as a development platform--they just happen to have the tools available for those with the know-how (many of whom would have come from the similar SmartThings environment--though differences are indeed generally documented). Sometimes forum posts have more helpful information than the docs, so if there's a specific method you're not sure of, a search here may help.

That being said, until that happens*, the docs are a wiki. It's a bit tricky because, on one hand, what is documented should be the way it works, and if it's not documented then we don't necessarily technically know how it should work; but on the other, it is a wiki and they do accept community contributions. So: just an idea for anyone who is confident in their abilities here.

*and my suspicion is that this won't be soon; staff have historically trended towards preferring to spend their time on end-user experience rather than developer issues. (I find this position quite understandable given the small size of their staff and the relative newness of the platform.) That being said, they are still quite responsive to specific problems developers may notice.

[maffpt]

Hi @bertabcd1234!

Thanks for the kind response - this community is awesome!

@bertabcd1234

Sometimes forum posts have more helpful information than the docs, so if there's a specific method you're not sure of, a search here may help.

So far I've been doing exactly that: searching the posts, here and in the web. However, I miss the full information about the environment - I usually go from there to search specific uses. And, to be honest, I don't feel comfortable to ask what I think are basic questions that a simple look at the documentation would be enough. I'd rather ask for help when I get a roadblock. But the sherpas are great!

@bertabcd1234

*and my suspicion is that this won't be soon; staff have historically trended towards preferring to spend their time on end-user experience rather than developer issues. (I find this position quite understandable given the small size of their staff and the relative newness of the platform.)

I agree with you: won't be soon ...

The staff size for sure is a limiting factor. However, I'd be glad to pay a annual fee to be a developer, helping them increasing the staff size, And documenting ...

@bertabcd1234

That being said, they are still quite responsive to specific problems developers may notice.

I agree with you again. This proximity with the platform developers is great!

@bertabcd1234

So: just an idea for anyone who is confident in their abilities here.

Unfortunately not my case - still climbing the Everest. Not even at the first base camp so far ... but I'll get there!

[dman2306]

I agree with the things you're saying, but let me put my business hat on for a moment. When you release products you release an MVP (Minimum Viable Product). Basically, what's the minimum amount of work you can do and turn a profit? Then over time you enhance it. I agree the documentation is poor at best. However, look at how many apps and drivers have been created using it... There's a ton of cool stuff out there that are pretty complicated! That means it's sufficient to meet HE's goal -- it has created a rich ecosystem of apps/drivers with minimal effort on the part of the HE team to document it. From a business perspective I'd call that successful! Meaning we have MVP documentation, it is enough to get mos developers capable of building what they want to.

The question is, if it's going to take X hours to document it better, how many Y dollars will it generate? My gut says, X = 200-300 hours, and Y = right around $0. So if I were the CEO of Hubitat, this isn't where I'd focus my efforts either. Instead I'd focus on two things - what features are required to increase market share and what additional revenue streams can be created?

Short story is, while selfishly I'd like the documentation to get better (I've submitted dozens of updates to it myself!) at the same time, I can think of a million other priorities that I'd rather HE focus on. Better documentation isn't going to sell more hubs. More consumer friendly features will sell more hubs.

[BrianP]

And the worst thing for developers and consumers is if Hubitat doesn't sell any more hubs!

We will get new features and a healthy ecosystem only if they stay in business. If anything, they should be focused on making it easy to set up for non-technical people, without removing the capabilities that make it so lovely for people who have enough knowledge to customize things.

The Hubitat Package Manager is a great addition for "aftermarket" apps!

[maffpt]

@dman2306

I agree with the things you're saying, but let me put my business hat on for a moment. When you release products you release an MVP (Minimum Viable Product). Basically, what's the minimum amount of work you can do and turn a profit?

I can't disagree with this reasoning - Hubitat is a business and the mindset should always be such.

@dman2306

Then over time you enhance it.

Isn't it the time to enhance it? I'll discuss it more ahead in this response.

@dman2306

I agree the documentation is poor at best. However, look at how many apps and drivers have been created using it... There's a ton of cool stuff out there that are pretty complicated! That means it's sufficient to meet HE's goal -- it has created a rich ecosystem of apps/drivers with minimal effort on the part of the HE team to document it.

No questions about that too !

What this community is producing is amazing - everyone is so committed and hardworking and helpful. I'm glad to "land" on this environment.

I started my career more than 40 years ago as a Technical Support Engineer and, in spite of rising through the ranks, I always kept the idea that a good infrastructure, not just sufficient but, for sure not overshooting it, is paramount to support business and I had a quite share of proof that this is a successful approach.

What I can imagine - and hope for - is how more productive the developers would be and more developers could be attracted to HE - again, hope for - if we have at our disposal a better documentation. How many new developers could join the ranks and how more productive could we all be if we have a better documentation available?

@dman2306

he question is, if it's going to take X hours to document it better, how many Y dollars will it generate? My gut says, X = 200-300 hours, and Y = right around $0. So if I were the CEO of Hubitat, this isn't where I'd focus my efforts either. Instead I'd focus on two things - what features are required to increase market share and what additional revenue streams can be created?

As of now, HE is not for the average user. However, I plan use HE hubs as my central strategy for my own Home Automation business and I'll need that it should be as user friendly as possible.

As I suggested in a previous response, why not we, as developers, could be a revenue stream also? I'd be glad in paying an annual fee to be a "Registered developer". I know that it will not be a huge revenue stream and for sure not the main revenue stream, but maybe good enough to support a dedicated team to support the community - and, of course, documenting ...

One of the features of HE that is usually praised on many reviews is its ability to be highly customisable and, in my case, together with the local processing capability and an active community were the main reasons to choose HE as my hub,

@dman2306

Short story is, while selfishly I'd like the documentation to get better (I've submitted dozens of updates to it myself!) at the same time, I can think of a million other priorities that I'd rather HE focus on. Better documentation isn't going to sell more hubs. More consumer friendly features will sell more hubs.

For sure more user friendly features will be highly welcome - and I'll need that. I'm betting on it !

Initiatives like Smartly are great Smartly - the Hubitat dashboard skin engine and I can't wait to use it. For sure a very nice looking and functional dashboard is fundamental to gather clients for my services and Smartly, AFAIK, seems to be really great.

@BrianP

We will get new features and a healthy ecosystem only if they stay in business. If anything, they should be focused on making it easy to set up for non-technical people, without removing the capabilities that make it so lovely for people who have enough knowledge to customize things.

That's why I'm confident that I did a right choice with HE: this community is beyond words - I can never stop praising it.

@BrianP

And the worst thing for developers and consumers is if Hubitat doesn't sell any more hubs!

This is something that worries me: revenue streams. I really wish that Hubitat become a unicorn - everybody will be thrilled with it, no question about that!

@BrianP

We will get new features and a healthy ecosystem only if they stay in business. If anything, they should be focused on making it easy to set up for non-technical people, without removing the capabilities that make it so lovely for people who have enough knowledge to customize things.

I believe, and I'm pretty sure most people here will agree with me, that this community is a huge asset for Hubitat. And I'd like it to grow and I believe that a good documentation would help more developers to come aboard.

@BrianP

The Hubitat Package Manager is a great addition for "aftermarket" apps!

The Hubitat package manager initiative is another example as how important this community for HE. I'll take a close look at it before releasing the app/drivers I'm developing.

Last but not least, thank you guys for taking time discussing this topic.

Peace and health for everybody!

[bcopeland]

@bertabcd1234

they do not bill themselves as a development platform

While this is true.. I have found it to be an awesome development platform..

So I guess..

[bcopeland]

And besides.. The steep learning curve may have been what enticed me even more... I thrive on a challenge

[markus]

Overall I agree with the above, but...

@maffpt

As I suggested in a previous response, why not we, as developers, could be a revenue stream also? I'd be glad in paying an annual fee to be a "Registered developer". I know that it will not be a huge revenue stream and for sure not the main revenue stream, but maybe good enough to support a dedicated team to support the community - and, of course, documenting ...

As long as this doesn't limit access to documentation and information for those devs that do not pay, this would be fine. If it gives extra things, like a separate corner in the forum for releasing code, priority access to the beta program and other such things, I'd be up for paying a reasonable amount (depends on what is offered) even though this is just a hobby for me and has nothing to do with my business.

@bcopeland

I have found it to be an awesome development platform..

It really is And a fun one at that!

I do recognize that it may be hard to start developing for this platform, even for a seasoned developer the first few hours can be challenging in finding your way. At times I still can't always find the "right" information easily, but that is less and less, until I do something with tech I've never touched before. But that would be the same for any platform.

[bcopeland]

@markus

And a fun one at that!

So agree..

[bcopeland]

And the positive feedback from the community on releases is quite addictive

[maffpt]

@bcopeland

While this is true.. I have found it to be an awesome development platform.

That's true.

@bcopeland

So I guess..

I loved the error message!

@bcopeland

And besides.. The steep learning curve may have been what enticed me even more... I thrive on a challenge

It used to entice me too ... but I think my age (59) is catching up and sometimes I don't like to spend time on things that I know from experience that should not be so difficult ...

@markus

As long as this doesn't limit access to documentation and information for those devs that do not pay, this would be fine. If it gives extra things, like a separate corner in the forum for releasing code, priority access to the beta program and other such things, I'd be up for paying a reasonable amount (depends on what is offered) even though this is just a hobby for me and has nothing to do with my business.

Again I agree 100% - I don't mind pay for extra benefits, since they are reasonable enough. Like flying Economy Extra - those extra 4 inches of legroom make a difference on a 9/10 hours flight and paying around 10/15% extra. Note: For sure Business Class should make a even better difference, but in my case, the I prefer using those extra $$$$ on other things, like traveling again

@markus

It really is And a fun one at that!

I'm enjoying it too - but it could be less cumbersome ... age problems, remember?

@markus

I do recognize that it may be hard to start developing for this platform, even for a seasoned developer the first few hours can be challenging in finding your way. At times I still can't always find the "right" information easily, but that is less and less, until I do something with tech I've never touched before. But that would be the same for any platform.

Again age related problems ... grumpy guy on this level of difficulty here, but a persistent one!

@bcopeland

And the positive feedback from the community on releases is quite addictive

As I said before, the reviews that I read about HE constantly commented about the strong and enthusiastic HE community, And it was a very nice surprise to get to know how awesome this community is. But I think I said it before, didn't I? age ...