I'd say I'm pretty familiar with how things work in HE. I love HE. I'd never look at any other platform. I'd love to be more familiar with it, but every time I find something cool that I want to do, I'm blocked by advanced language documentation. Don't get me wrong. I love that we have so many great people around here to keep this community moving forward and developing new ways to integrate things in to an environment, but hear me out a minute. Every time I find something I want to do, the documentation is either advanced or incomplete. I'm not a programmer. I've never claimed to be, I deal with computer hardware and stupid end users mostly and learn things as I need them and as I go. So, for example, something telling me to enter a token I have no idea where to find is a bit frustrating. And no documentation anywhere on that token. I'd love to pull up a here's how you do this, my post of bragging rights, look what cool thing I've done, and you need this connected and here are the answers for this part of the connection. Even if it's a link to a great explanation of how to find that token or whatever in another post. You know how is HE supposed to move forward with new users that are NOT as skilled? Pretty soon all the smart people are going to own the hub, and then what? I know that I can ask questions here, and I've made a ton of amazing friends that I can ask and hopefully help people that are readers like myself in the future. But not a lot of newer users will take the time or feel comfortable right away asking a thousand questions. Me? I don't care. I'll ask. And ask again. And repeat until I get it. But sometimes, I like the independence of being able to figure it out. Sometimes that's impossible here. I'm sorry, I'm ranting, but the last few projects I've researched have taken twice as long as they should because those that posted projects just assume that you know certain hidden Easter eggs that would make the project the tops. This community is great, and I have no complaints about that, but I just find it frustrating sometimes that that one sentence could change the amount of time someone spends understanding a project.
I work in IT and see it all the time. "Smart" people take things they do naturally for granted. We all have our strengths and weaknesses, but it is sometimes hard to look outside yourself and recognize them as unique to you. With these things being "easy", there is no need to documented them, right? Unfortunately that is human nature. Thankfully in IT we are trained from day 1 to document EVERYTHING.
I totally agree it would be great if more post took time to document some of their awesomeness, without any fear of being ridiculed, or "over simplifying/complicating" the topic. Some do some don't. Praise those who do, and lets encourage those who don't.
It’s that old saying .. Programmers should not write their own documentation..
You get better documentation when someone not familiar with the code writes the documentation..
To make this actionable, should we start a thread where we find incomplete or lame documentation, post here and suggest edits?
I'd be happy to contribute.
I hope you aren't thinking we consider you as a token girl.
Perhaps the admins have a place for a reminder?
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!
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.
Is the problem in these places?
- Developers(like me) that won't put in instructions
- HE app instructions?
- Developer documentation for APIs?
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.
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?
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.
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.
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.
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.
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!)
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.