New User documentation

Relevant recent pull request for Linux installation document

I’m a long time openHAB 1.x user and am in the process of migrating my system to openHAB 2.x. Now that openHAB 2.4 includes the new Z-Wave binding and writing rules in Jython is now possible in openHAB 2.x as well, I feel that now the time for me has come to make the jump.

So I know my way around in openHAB but I’m always interested to learn from other people. This morning I was reading the forum and got triggered to read the documentation when I ran into a kind of ‘you’ve lost me here’.

  • “Of course, this is the correct.” I don’t know what the writer is trying to say here, ‘Of course, this is not correct.’ or ‘Of course, this is the correct representation.’, or may be something else, so “you’ve lost me here”. I have no clue.
  • The italic part can (IMHO) be completely removed since it seems a little far fetched to me. Does anyone seriously do this? I mean, it’s certainly a creative solution, but also a solution triggers so many questions (how does this work with direct sunlight on the sensor, multiple lights on dimmers which could cause false positives, etc.) that this seems to be more a topic for a forum post where it can be discussed than that it should be part of the documentation. Or may be something for an ‘advanced solutions’ section of the documentation.

I hope I didn’t step on anyone’s toes here because that is absolutely not my intention. I appreciate how much time and effort everyone puts in this.

Just to be clear, OH 1.8 supported Jython and OH 2 had supported it since at least 2.1. I don’t want anyone to have the mistaken impression that this is something new.

One thing to note is this section of the docs is not describing anything new. OH has always worked this way since at least 1.6.

The writer is saying that the UI is behaving correctly given the scenario presented. A command was sent to an Item to turn ON. The Item’s state charged to ON. The device didn’t turn on because of some problem. So the UI and the physical device are out of sync.

If you want the UI to accurately reflect the state of the device, you need feedback from the device or some other sensor to tell you the light turned on or not.

The short answer is yes, people do this. Usually it is something more critical than lights like irrigation or heating.

That’s why I wrote 2.x and not 2.4. I was just providing a little context why it has taken me so long to jump on the 2.x wagon.

I know, not sure if I used 1.6, but 1.7 for sure and I’m still running in production with a 1.8/1.9ish version. I was mainly referring to the text which I made bold. The sentence “Of course, this is the correct.” simply isn’t correct English. So that’s where I came to the point that Andrew asked for to point out:

Then may be it would be better to use irrigation or heating as an example here. Still, I think it takes away the focus from what is being explained and hence should be a topic for an advanced section in the documentation.

I’m just providing some feedback on how I perceive the documentation.

much appreciated as well.
If I’m not mistaken, you are quoting me from the ‘concepts’ post above. That page is part of the eclipse smart home documentation. The concepts page is a target for improving the portion of the documentation considered important for new users. Thank you

I have been banging my head against OpenHAB for many hours over weeks of time. I have RTFM many times. I am sick of Things and Bindings and all the other things that I can’t relate to without using them. My eyes have glazed over.

A newbie doesn’t want options and selections. “Just do xxxxx”.
I just went through the 50 posts in this thread and “hearted” about 3 or 4. Good stuff. But most of the comments were over my head.
Also, I don’t know if the Demo link on the home page is part of the documentation under consideration here but it does nothing for me. Five boxes. Click REST API and get a bunch of text. Huh?
Maybe I’m too old or dumb but I have been writing code for over 50 years and have been able to hack into anything I needed but the OpenHAB documentation is too complex or OpenHAB is more complex then it needs to be.

My $0.02

Your comment leaves me a little puzzled.

If a binding is properly configured it’ll work on any platform (Linux, Windows etc… or did you misunderstand “platform” ?)

Yes that’s any virgin’s wet dream. But just like in real life, it just does not work that way.
There is absolutely no such thing as a standard home (in terms of devices) or standard automation ruleset. So no matter how educated you are, you have to make your own choices. No developer can do it for you.

err? What do you want to do without devices ? Ok there might be some some use cases but those would clearly be corner cases that the documentation isn’t written for. The mainstream target audience will want to control their - already owned - devices.

What documentation do you actually refer to ? I’d think that the current one is a lot better (more streamlined) than it was beginning of this year when this thread was opened to address that.
And on complexity … well, that statement applies to any system that isn’t tailored to your specific needs but this is how SW works. Most of us use and love OH for it’s versatility, and you cannot have versatility without complexity. Yes that makes it more complicated for beginners but then again it’s no dead end like most competitive commercial solutions out there are.

Remember, I don’t have any devices I want to use with OpenHAB right now. Just do something so I can get the feel of using OpenHAB.
So when I said, “One specific binding” I meant something that would work on RPi or Windows or what ever platform for a system without any devices (yet).

“There is no standard” Well, maybe my home is a standard because it doesn’t have any devices. So what things can I do with OpenHAB now and how can I do those things?

The documentation I refer to is the link I get to by clicking
“Getting started? Please refer to the online documentation.”
I have been there many times. Nothing from that link tells me how to actually do something end-to-end on OpenHAB.
A few weeks ago I did try to follow the Windows procedure and got to some Network binding as instructed and concluded it was broke.

I figured maybe I could do something with weather because that shouldn’t require any devices. So, I have been trying to install openweathermap. I bounced around like a ping pong ball trying various things and got somewhere but not to the end. Then I found this BasvanH post:


That at least has a somewhat step by step procedure.
So far I got to “import widget to your HABpanel”. I need to find out how to do that from the OpenHAB documentation.

If I ever find the steps to go from nothing to a working openweathermap I will type up the steps. Then if there are others that are as inept as I am it might help them along.

Or try the demo package. That works without real devices.

No that is an exotic case. Which you can’t expect the docs to be written for. I guess that’s why you have the feeling the docs are not made for you.
Everybody else is starting with one or a number of specific devices that (s)he wants to orchestrate.
If you want just something to play with to get an idea of the look and feel, as @gert_konemann correctly points out, you could try the demo setup.

There’s gazillions of possibilities, way too many to list (although granted most of them would start with “I have a device X”). But remember everybody has different devices and use cases, so there is little point in giving step-by-step directions for a specific device/case.
If that’s what you’re looking for, you’re better off with this forum or a search on G**gle or Y*utube.
And if you’re seeking general advice on home automation e.g. which tech to use, then you mustn’t expect to find that in these docs.

Well, there’s a section on this right on the main page you claim you have read many times. There’s even a link to the new user tutorial.

What procedure do you refer to here ?

The documentation is complex because openHAB is as complex as it needs to be.

If you want simple then you need to look for something that is less capable. Many commercial options may for the bill for you. But any platform like OH that supports the bridging and interaction of over 350+ different apis, protocols, and technologies is going to be complex.

Did you actually read that text? Did you see that is interactive, leaning you see and experiment with each and every API endpoint, and it gives you the equivalent curl command. What more do you want from documentation for an API?

Maybe I don’t understand what you are trying to do or where you are getting lost. Perhaps this post can help: How to get started (there is no step-by-step tutorial)

There are a bunch of getting started resources there including links to YouTube videos.

Then you should completely ignore bindings and Things entirely and create Items and roles and UIs only.

But that isn’t how most users get started with oh so that isn’t what the docs are geared towards. It’s worth noting that the Demo config is just such a setup.

Maybe don’t completely ignore Things and Bindings, but sick to generic ones that will be useful even if you don’t have devices like one of the weather Bindings, Network, and Mail, for examples.

Not a whole lot that will be terribly useful. Maybe set it up to watch your devices and services and alert you when one goes offline. There are better tools for the use case but it will exercise much of oh. I do this in my system mainly because my automation may make different decisions when certain devices are offline.

That’s partially because there really isn’t just one end-to-end. There after many and its hard to stroller a balance between being thorough and overwhelming the user with lots of stuff that is irrelevant to them, or just providing detailed docs about reach potential step along there paths and there user needs to determine what their end-to-end path includes.

But, as always, anyone is welcome to write, edit, and/or improve the docs.

That would be most welcome.

Which unfortunately is incomplete. I have pointing new users at it because it is still riddled with TODOs. I keep thinking about picking it up but at this point it seems that effort might best be left to when OH 3 starts to be a thing.

I was hoping that bartus’s tutorial would become the new users tutorial at some point but I think that work had stalled. But what exists is in the link I provided above.

Holy… dog gone dude…yeah… YEAH!!!
agreeded yes… fully agreeing

I;m… look really sorry comments I made almost a year ago are now being dregded up but gosh do they ring true?

I will try to address all the comments in chronological order.
Demo Package
Start at the first box at the upper left, REST API. Click and I get a list of 19 items on the left and some links Show/Hide, etc.
Explore button at top does nothing. Click the first item (bindings) and get three lines click one of them and get "Response Class (Status 200)…
I’m lost what am I supposed to do with this stuff?

This sectionhttps://www.openhab.org/docs/#putting-it-into-practice

It tells me what to do but not how to do it.

New User Tutorial https://www.openhab.org/docs/tutorial/
First page, good. Second page good. Third page and we are into “options” , Paper UI, Basic UI, etc. Newbies (like me) can’t handle options yet.

What procedure?
I started a thread about my problem back in June:
https://community.openhab.org/t/network-binding-search-finds-nothing/76872

Post 17/21 Rich Koshak said:
"Hmmmm. I vaguely remember there some threads about Network binding always reporting everything as online in Windows, but I thought that got fixed. But since 2.4 is more than six months old now I’m going to guess that it was fixed after that release. You might try moving to 2.5 M1 or the latest snapshot and see if that works.

Rest assured, I don’t think you are doing anything wrong. I think the Network binding is broken for your version of OH on Windows."

So

I may be the densest, inept, dope to try to use OpenHAB but I think I need the “Hello World” version for OpenHUB. How to do something end-to-end in 10 steps or less…or 20 steps or less…or 30 steps or less or whatever.
Do something that will work for any newbie. I thought weather but maybe something that uses the sound card or a thumb drive.

If I were to characterize the current documentation I would say it leans more toward a User’s Reference document then a Where To Start.

When it comes to documentation I always warned co-workers to beware of two things.
(1) MIGO…Mine Eyes Glazeth Over.
(2) “Ask an engineer what time it is and he’ll tell you how to build a clock”.

But that is what OH is. It’s a box full of gears and axils and ride and such that one can use to build a time keeping piece. Some may want a watch, others a clock tower. The instructions need to be written so you can build your own custom time keeping piece.

OH is a development framework upon which to build your own bespoke home automation system. There is no end-to-end, there are thousands of end-to-ends.

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.

This.

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.

How to get started (there is no step-by-step tutorial) is now going to be my stock reply. At least on person on this thread bothered to click through.

3 Likes

Perfectly right! The docs are quite good for probably every level of user!
Sometimes we forget to value that and simply say: Thank you!

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

2 Likes

Closing the thread at the request of the OP.

1 Like