I understand were you´re getting at, but (as usual one might say), I dont agree.
I believe the documents could be better than just complex, specially for new users. But as we have talked about so many times, there is a need of someone doing this. We all know, the developers cant do it, (not at the needed level), they concentrate on developing. So someone needs to grap the ball and do it.
But thats just my opinion. I know it will require alot of rewrite which mean alot of time. I dont blame anyone for not doing so. But thats why it´s complexed as it is.
Apparently the people who are volunteering to contribute to the docs are not doing a good job in a lot of user’s opinion. But none of these complainers are doing anything about it. And so once a month or so we get to hear someone who is apparently frustrated come on this forum and tell us how we are doing it all wrong and offer all this wonderful advice about how we need to write the docs better. And they all have the same attributes:
they aren’t volunteering to do it
somehow they think all the advice is something new to us, “Thank you new user! If only we had realized the docs were complicated we would have made it simpler! I never would have thought of that.” We were all beginners with OH at some point too. Many of us have spent hundreds of hours helping new users with problems. And some frustrated new user posts essentially the same post once a month. Do they think we don’t know? Do they think their sage advice is something we’ve never thought of over the years?
they all underestimate how hard and complex home automation is in the first place
they don’t give us any credit for perhaps knowing stuff they don’t
But of course the other side is the thousands of users who have found the docs to be adequate and useful to get started with OH and use OH never post about it. We never hear from them. All we hear are the complaints. Interestingly, those tend to be the users who do volunteer to help with the docs.
So are the docs really as bad as everyone who posts to bitch about them, or are a lot of these users coming to openHAB with false expectations? I don’t know anymore. And honestly I’m done typing the same stuff every time it comes up.
Kim
This is an old thread. It sort of sparked a movement to try to make the new user docs better. If you think they are bad now, you should have seen them before. @lipp_markus (who is a professional documentation writer) rewrote the whole new user doc. He did a fantastic job and carrying on about it is almost insulting to the effort I myself made and Markus borders on insulting. Here is a link to the (now closed) thread.
I may close this thread as well because this is a point less discussion as Rich has said.
Thanks Rich, you put it better then I ever could
