Couldn't agree with you more @april.brandt ! Over the last few months I've really lost interest in any "new" projects for HE due to this exact same reason. I'm happy with just a few "simple" projects for my HA & don't care to delve thru the "advanced documentation" at my age....nor does my wife! LOL
I don't really see myself continuing on with HE within a couple of years as I'm not a "tinkerer".
Thank you again for your post...you echo my sentiments well!
6 Likes
1 Like
I'm going to make this a goal. But not in a public way. I'm going to start PM'ing about this. I don't want to turn it into something that people are afraid to post because their documentation is missing a taken for granted item. I will respectfully ask them about it and respectfully ask them to add it in to their documentation. I would encourage others to do the same. I believe that in doing it that way, friendships will be forged and trust will be established. It's the only way I feel like it's respectful. I think that if you ask most people here, they'd update their documentation if asked.
6 Likes
Is the problem in these places?
- Developers(like me) that won't put in instructions
- HE app instructions?
- Developer documentation for APIs?
1 Like
I have found that people do this already at least in my experience writing a driver.. also people involved in beta testing should do this as well - ask about docs/review docs etc. all very important.
1 Like
So, you're saying you'd rather not hear anything at all if the person isn't willing to go into what you think is an acceptable level of detail? Because I think that's what the result is going to be. Someone is already taking time out of their lives to share something with the community that they are not required to. I would think you'd just say thank you and then ask your questions rather than criticize the level of detail they've gone into. It's your choice to try and duplicate their results. If you're not able to, that isn't their fault. Don't use it. Or come up with your own. You wouldn't have had it if they hadn't shared at all either, right?
2 Likes
Ah.... You hit it on the head, and it's the reason I don't share a lot of my code to the community (this and others). I don't have time to make generic documentation, and don't have time to field 1000 questions.
Any time I put something out "as-is" it never ends up being "as-is", either.
Anyway, my only point in saying this is that be careful what you ask for.
I think it is 100% acceptable to push Hubitat for better documentation - it is a commercial product after all. And they have been very willing to improve it when requested.
I don't think it is realistic to expect people putting out things for free to spend even more time writing documentation. Just my $0.02.
7 Likes
I agree with this too .. anything that is done "for free" is not / should not subject to someone else's desires. That doesn't mean (in general 
) you can't make requests though and also it doesn't mean a developer is "wrong" for rejecting those requests as well.
Agreed, in general.
1 Like
Are people here really saying that they wouldn't appreciate if someone like me, or @april.brandt took time out of our own days and families to offer up some help and suggestions to make any documentation you put out better, which could help result in you getting less questions and help out our HE community as a whole?
Hmmm... that's... odd... to say the least.
2 Likes
Yes. I am saying that.
What I put out I consider "as-is". As such I'm not all that receptive to comments on improving the docs. I don't get offended by the suggestions, I just mainly ignore them. I know many other developers like that, too.
On the counter, there are many developers that ARE interested in the feedback, so it is worth asking/suggesting and see where it goes.
Obviously if someone else wants to make their own set of docs, that is their prerogative.
That's not what I'm saying at all. What I'm saying is that your first reaction seems to be to criticize rather than say thank you. If the person who shared their project hasn't lived up to your expectation, they shouldn't discuss what they've done. That seems to be what you're saying.
No one is holding a gun to your head saying you have to do what they did too. And if you can't, that's not their fault. As frustrating as it may be. Trust me, I've been there too.
1 Like
Great, I won't spend any time trying to help you then. Have a great day. I'll spend my time with those who would appreciate the feedback. (Edit: I'm not being sarcastic, I really appreciate you are self-aware and vocal about this, as it helps me too, so thank you!)
2 Likes
This is literally giving me flashbacks to 3rd grade English class. Each week, we had to write out a set of instructions on how to do a simple task. Then, on Friday, our teacher would follow our instructions EXACTLY. If there was any way that she could technically do it per our instructions but not the way we meant it, she would. It was simple things like making a PB&J, opening a wrapped hard candy, etc. I learned early that when writing instructions you have to write to the lowest common denominator but, here, you don't want to insult someone by assuming their level of ignorance. The range of expertise in this community is so diverse that it's often difficult. Sometimes it takes a newbie to help a newbie. And writing documentation for these elaborate integrations is probably as difficult if not more than writing the actual code.
6 Likes
LOL. Whatever.
I never said I'm not willing to help or discuss. I did say that I am not interested in suggestion/comments on improving docs for things I release.
1 Like
That's weird, where have I done this anywhere including on this thread?
This isn't 3rd grade Englsih. No one is giving us grades and we are not being forced to release anything. What, are we only going to be allowed to discuss things if the posts live up to your standards? Don't read them. Don't follow them. That's your choice. The sense of entitlement if amazing.
"You did something great and therefore you must make sure I have that great thing too." I'm sorry but it doesn't work like that. Just because someone knows how to do something doesn't mean they owe you and have to teach you how to do it too. Maybe their post inspires someone else to document it in a more thorough way. Maybe someone comes up with a better way to do it entirely. Just because you can't follow it doesn't mean it can't be helpful to someone. What you are suggesting will just cause people to stop posting anything.
Sorry, I realize my comment came off as negative. What I meant to say is I really appreciate that you are honest about how you'd take the feedback, which is awesome as it would save someone like me time from trying to help out. Again, I apologize if it came out different. I edited above.
3 Likes
I knew it would turn into "if you don't like it leave". That's not it. Someone posts a project and leaves out information because it's assumed that you know it. I said that I would pm a person. And not start any trouble asking if they could insert documentation that I've possibly written or found. NOT to chastise, but contribute to their appreciated efforts. You immediately jump to the conclusion of criticism, which was not the reason for my mention in this topic.
9 Likes
Fair enough, and sorry for my somewhat over the top response. I edited it to be less pissy.
I understand your comment. Better documentation is better for everyone, and making suggestions should always be fine. My only point is that there is no obligation on any authors part to incorporate the comments or suggestions.
That's why I have a lot of respect for Cobra, Brian, Steve, Kevin, CodaHQ and many others on here that are willing to provide so much of their personal time for free projects. Because I sure won't do it.
Don't get me wrong, I contribute a TON of code to open source projects. I am not that interested in providing much code for apps on a commercial hub. 
Why release something that is a ton of work and effort for me, just to make a commercial company money for free?
5 Likes
