Getting Started with OH3: rewriting the tutorial - 1. Introduction

First, a word on the order of the sections in the docs. It assumes users read them in order, that is, first the concepts, then the installation guide, and when they reach the tutorial section. I’m not so sure about this so I’d suggest to call the tutorial Getting Started or similar and move it to the top. Then the tutorial intro’s first paragraphs could be a quick overview (or recap) of the concepts and the installation options, with links to the other sections (Concepts and Installation Guide) to go deeper.

If a document is short, I think more people are likely to read in order, beginning to end. The longer or more complex a document gets (and that’s just unavoidable depending upon the topic), the less likely people are do this. In an age of hyperlinked documents, I think many people will jump around to what interests them after a certain introductory point.

Also, I’m not the biggest fan of the content on the entry page at https://openhab.org/docs/ , especially the “motivational speak” right at the start (“keep your focus”, “result of hard work” etc.), IMHO that page should go back to describing with a neutral tone how the docs themselves are organized, i.e. what the sections are and what you can find in them. That content could however be a good fit for the introduction of this tutorial/getting started section. The only section I would leave there is the “openHAB community” and maybe the last one about architecture.

I think there may be a good compromise between the two point of views. I too could do without the What You Need to Know Before You Start section. My main objection is that it really doesn’t tell much. From my point of view, the summary is “OpenHAB will take some work to get up and running.” Okay, that’s fair enough, but what does it really mean in terms of time and effort? The short answer is that it’s going to vary tremendously based upon the knowledge and experience of the individual. So, what I’d rather see is a link to another page. Perhaps the link could be titled “Is openHAB Right for Me?” On that page one could go into the motivational discussion, discuss openHAB vs openHABian, and discuss hardware choices.

You need to sit in front of a computer with access to the files to make changes.

Under file-based CONs, I see the above. Isn’t it redundant though. Something similar enough is true of a GUI-based CON.

Maybe it wasn’t clear enough, what I meant is that you don’t need a full development environment or files shares or shell access to the server; in this scenario you can make small adjustments even on your phone - it was in contrast to “All objects can be altered from anywhere the UI can be reached (including on mobile)”

That’s a good compromise.

I think this summirizes the problem. I guess I’m still sitting on the fence on this - providing a representative example of the smart home world, even if it’s only for illustrative purposes vs. a example that can be reproduced while following the tutorial but isn’t really what openHAB is about.

Maybe we ,split the difference and provide two simple and intermediate tutorials, one that is more typical (i.e. what is already there) and two that no matter what the users can follow along with.

Yes, or maybe adapt the language so that we don’t provide detailed instructions for specific hardware, but give some generic instructions (like it’s done in https://support.apple.com/en-us/HT204893#add for instance), i.e. “look for the binding corresponding to your appliance or service and install it, check the binding docs to check if you have to add a bridge manually before things are auto-detected” and so on? The screenshots may give an example of a specific binding as an illustration but the text wouldn’t assume you’re using that one specifically.
For more advanced tutorials, then stating the prerequisites from the start would make these assumptions clear, and the reader would normally (hopefully!) be familiar with the basic tasks anyway so they could adapt if they’re not in that particular scenario.

1 Like

Hi,

I discovered OH2 a few month ago, and here is my feedback on documentation. I consider myself as “power user”, or even “specialist” as I’m an embedded software engineer, and I must admit that I had a lot of troubles to implement some quite simple scenarios (I keep a file-based approach).

  • The given examples do not work “out of the box”, we have to interpret a lot of things, and more have to look on forum (very rich BTW) for a complete working example
  • A lot of bindings does not even include any code extract to start on a first basic scenario
  • Simple things like “I collect the electric meter values through MQTT and I want to compute at midnight the daily consumption” took me like an hour to success : simple math operations are not clearly described (need of local variable etc.)
  • English only. Not a problem for me, but I can help to translate in French :slight_smile:
  • I would also consider to create a tutorial (or a full set of out-of-the-box scenarios maybe ?) which would not need any IoT device, so that anyone can test immediately. Only with software we can image a lot of scenarios based on time, sun position, weather forecast, network devices, MQTT broker, persistance etc.

Anyway thank you very much for this effort to rewrite documentation, this is a huge work (and I can help !)

3 Likes

I get what you mean, and that most of the struggle seems to be from “getting the basics in order” to building intermediate-level stuff; but what I wonder though is where we end the “Getting Started” tutorial and directing users who want more to the community to get help and often ready-made examples.

What I’m trying to say in my last few replies is, I’m not sure what the profile of the average reader of this tutorial will be, but I fear if we restrict our examples to “monitoring your local network” and other generic things like the weather, we’re kind of missing the point. There are better tools than openHAB to do these things. If we’re targeting people already educated in what home automation is and how it can help, then sure, they will understand the generic examples; but if they’re not, maybe it’s better to provide examples involving some real hardware.

What I usually reply to neophytes asking about home automation, and what it could do for them, I usually try to focus on easy-to-explain, easy-to-understand examples that might be relatable to them: like the “make the Hue lights and the connected plug you got last Christmas work together to notify you when you have to pick up the laundry from the washing machine” (and without some big-tech cloud service) scenario I offered to include as the last part of the tutorial. It’s perhaps not the quintessential example but I found it had the best “uh, okay, interesting” effect - though I also get “you could simply use a timer” sometimes :laughing:.

But I somewhat I agree that involving more things with no dependency like “when the sun rises” could have the same effect.

One of the weather monitoring systems i used shipped with a driver for a dummy driver to simulate data so that people could play with the UI part without having to have a connected weather station.
So one possibility might be to create a simulate binding that pretends to be a light (maybe with some simple ui somewhere that has light/switch status) but essentially behaves like the Hue binding so you could use the hue binding if you have it or the simulator if you don’t.
Downside is that somehow we would need to create a simulator binding that can be used.

On the temporary testing/sandbox instance I set up, I added the Nibe Heat Pump binding, and found out you have some simulators - they’re easy to add, and provide changing temperatures and simulated failures. That could be an option.

(And, it makes decent visualizations of persisted data:)
https://ohui.azurewebsites.net/#!/page/hourly_combined_chart
https://ohui.azurewebsites.net/#!/page/pump_gas_heatmap
https://ohui.azurewebsites.net/#!/page/pumptemp
https://ohui.azurewebsites.net/#!/page/calendar_brine_temp

Hi @ysc,

You wrote:

I’m not sure what the profile of the average reader of this tutorial will be, but I fear if we restrict our examples to “monitoring your local network” and other generic things like the weather, we’re kind of missing the point. There are better tools than openHAB to do these things. If we’re targeting people already educated in what home automation is and how it can help, then sure, they will understand the generic examples; but if they’re not, maybe it’s better to provide examples involving some real hardware.

Just my two cents, with any technical documentation, I think it’s critical to identify who the target audience is. Perhaps the safest assumption to make is that reader of the tutorials has a vague understanding of home automation and what they want to do, but no prior knowledge of openHAB. (That’s probably not an accurate representation of the user base, but it probably is the lowest common denominator.) In any case, it might be a good idea to preface the tutorial with who it’s intended for and what skills the reader is assumed to have. Also, I wonder if parsing the forum for the last year’s posts would aid in understanding pain points of users.

Regards,
Burzin

I don’t think anyone is arguing any more that we restrict exclusively to those scenarios. I think what is being suggested is that we include some. So don’t get rid of Hue and Zwave but add in something like Network and OpenWeatherMap in addition.

Based on what I’ve seen, those who use the Getting Started tutorial will be those who are completely new to OH. Some are new to home automation completely, others have a specific problem they are looking to solve, and still others are looking to migrate from some other home automation system. We need to support all three types in the Getting Started tutorial. That will mean that those who have a bit more background in home automation might find a lot of stuff that they already know but they should also intuitively know that a Getting Started tutorial needs to support those other two types of users as well.

I think this is the crux of the problem. Let’s take the true new user, doesn’t know much about home automation at all. If we only present Hue, Zwave, and MQTT and that user doesn’t have any of those technologies, we are forcing this user, who doesn’t know anything about home automation yet:

  • figure out which of those three example is most similar to the hardware they do have so they know which one to try and translate to a different binding
  • they have to translate the steps and screen shots to actually use those tutorials because what they see won’t match what’s in the tutorial (this is typically considered an intermediate level tutorial, not a beginners)
  • or if they decide not to try and follow along they gain absolutely zero physical experience operating openHAB by the time they are done with the tutorial; they really haven’t got started.

Also, given the different styles of learning (some learn best by doing) and the psychological importance of achieving small successes along the way to reinforce the content and give the user that feeling of “I can do this!”, I still think it’s important that we present, at least in part, something that the users can actually do regardless of what hardware they may have, even if the use cases are not typical home automation tasks. Otherwise, for many users the tutorial becomes a wall of text and screen shots without meaning; they don’t learn well by reading.

This is a case where there are two competing desires:

  1. make the examples representative of what home automation is
  2. make the examples something anyone can follow along with regardless of hardware.

Both are important but I think we are doing a disservice to truly new users if we completely ignore 2.

I at a minimum at least skim almost every new post to the forum. It’s kind of hard to pinpoint single pain points as most of those who do post for help simply ask for "Where is a setp-by-step tutorial to use <insert specific technology(ies)> to <insert some specific behavior> in <insert some specific manner>. As I usually respond, they won’t find that specific tutorial because everyone’s “insert” in that sentence is different. We’d have to write over 300! (300 factorial) tutorials to cover all possible combinations.

So, since we can’t do that, we need to make the Getting Started tutorial rich and complete enough to teach the stuff that is going to be universal to all use cases:

  • installing and configuring a binding
  • discovering Things
  • manually creating Thing
  • creating Items and linking them with Thing’s Channels
  • creating rules
  • creating the UI (sitemap)
  • setting up and using persistence

Over all, what is presented covers all of these and does so pretty well. But I worry that the great leap (there always seems to be a great leap) will be taking the examples (or is it one unified end-to-end example?) presented in Getting Started and applying it to their unique use case. If we completely exclude using as examples any bindings that are universal (i.e. don’t require any specific hardware or accounts) that great leap is even larger.

1 Like

For what it’s worth, I agree with you.

But I worry that the great leap (there always seems to be a great leap) will be taking the examples (or is it one unified end-to-end

Regarding the point above, I think a single unified grand end to end example may be counter productive as folks may look at it and say to them selves that’s for “x” and I use “y”. The purpose of the tutorial should be to illustrate and teach concepts that can be applied to the users’ problems and available technologies, so being broad, rather than narrow is probably best.

The counter argument is without an end-to-end example being worked on in Getting Started we lose the ability to demonstrate how all the piece parts of openHAB work together. If each page stands on it’s own than we haven’t demonstrated how it all works together. We would be missing:

  • how Things interact with Items
  • how Items interact with Rules
  • how Items are represented on the UIs
  • how Items interact with Persistence
  • how the Item semantic model helps with creating UIs
  • an end-to-end example going from hardware to rules and UI which is ultimately what the reader of this tutorial is after, how to get started stringing all this stuff together.
                                                     /-> User Interfaces
hardware -> binding -> Things  -> Channels -> Items |-> Rules
                                                     \-> Persistence
                                                      \-> Model

Most of the above becomes implicit and obvious when, for example, you create or discover Thing(s), then use those Thing(s) when linking to Item(s) on the next page that talks about Items, then use those same Items in the discussion about the other concepts. That makes the connection apparent and the repetition reinforces the earlier lessons.

If we go too broad and don’t have that repetition we run the real risk that the Getting Started Tutorial becomes the Getting Started Reference Guide. A reference is great and we need that too but it’s only really useful when you already know enough to know what to look up and where. It’s not so great at teaching the user how it all works together or how to get started. If it did, our current docs for 2.5 would be fantastic.

3 Likes

Speaking from the experience of someone who started with OH later in the day than a lot of you (i.e. OH 2.x) even knowing that text based config was possible I still elected for UI based config initially.

I’m a Software Engineer and knew that I’d probably prefer the control of the text based config at some point but it was still, IMHO, the wise decision to go UI based 1st as: 1) it got me up and running quicker 2) it meant I could quickly evaluate OH to see whether it suited me, without the need to learn a lot of text config 3) I was able to learn how OH “worked under the hood” 1st, which proved invaluable and then made the transition to text based config easier as by then I actually understood how Things, Items, Channels, etc all related to each other.

Now I do everything by text based config including setting up my own home made IOT devices, but I wouldn’t have been able to do it as easy without first playing with the UI configs.

Personally I didn’t find migrating from UI to text based that difficult, because by that time I understood OH, which I think is the critical thing.

Going head 1st into text based config I think is harder than the migration from UI to text based.

So in my opinion a bias towards the UI based config for new users isn’t a bad thing, especially if you’re explaining that there is the option to go text based if they choose.

Totally agree, it was initially confusing how everything worked together. Even a simple end to end example would have been useful initially, something like a simple Pingable Network Device which recognised when your phone joined the network and then sent a notification to your phone via the OH app to say “Welcome Home” would do as a start.

Then you could possibly have a more complex example where one of more Things interacted together to alter the state of another Thing.

1 Like

As an openHAB user from OH1.0 up to now, I have to veto. I set up openHAB1.0 in 5 minutes and got it up and running with the demo. This was my Windows Desktop Computer.
The first thing I made after I got openHAB up and running, was to install the knx binding and to add one simple Item to switch one Light through the demo (just added my Item…). This was another 5 minutes, because I had to lookup the group addresses which are essential for knx communication. 10 Minutes. Really!

I was very impressed and setup a vm to host the openHAB server. This took some time, but in general it was the setup of java, all parts were manually installed and as I did not install java in debian before, I had to lookup how to do this. But finally, I got an openHAB vm and since then used it.

In question of openHAB2, I found it much less convenient for my needs (well, no auto discovery with knx…) and much more complex to understand. Text configuration was so simple!

I think, the whole point is, to do it step by step.
First step should be a simple demo without any hardware. Then get the correct binding for your first piece of hardware to include. Get the first Item to switch or display something real.
Repeat until finished :wink:

1 Like

This perfectly describes my user experience with openhab2, too.

A graph like this HAS to be in the docs! It’ll make things much clearer.

2 Likes

OH3 could contain dedicated simulator binding, which provides collection of different kind of things.
Simulator binding could also provides HW simulation web page for things, where user could see the real hardware behaviour and change the HW state.

E.g. TV thing, simulation web page shows real picture of the TV and TV remote controller. When user “plug” power cable from web page, user could see that OH discovers the TV and/or thing is set to ONLINE. User could change volume via remote controller or from OH and see how both parties behave.

Simulators doesn’t need to cover all functionality, but just few basic functions.

One simulated thing could be more complicated which introduce also bridge in the game like HUE bridge + bulbs.

This kind of simulator binding would not be just usable for tutorials, but could also be used to test new concepts. So when new concepts are added to OH, users and binding developers could study OH features via simulators and eventually simulator binding code would be the reference implementation for binding developers.

If only it were complete. :frowning:

I once drew such a graph a long time ago (OH 1.8 days), not sure what happened to it.

Not shown is that channels can interact directly with Rules (Trigger channels), Things can interact directly with Rules (Things status triggers), Rules can interact directly with Things (new OH 2 style Actions) and that’s not even beginning to address new capabilities with the OH 3 rule engine where Rules can create and/or modify Things and Items and such.

It also doesn’t show how this all operates on an event bus so those arrows aren’t really direct communication in all cases. Some go through the event bus, others go through the OH core API, etc.

As an incomplete model of the relationships between concepts, the above is OK. But I fear it’s too incomplete and thus gives a false understanding of what’s going on. And once we add in more details I fear it become too hard to follow. Not sure how to handle that.

I’m aware that this a rather huge simplification but it’ll do for beginners. I even think it’ll do for 90% of the openhab users.

Imho this is intended to visualize the abstraction levels and thus this doesn’t have to be shown.

Maybe we’ll add a “Below is a rather simplified overview of the abstraction levels in openhab”.

2 Likes

I agree. Then stick the more complicated map into one of the advanced topics.