Tutorial (beginner) feedback

[grubstake]

Since you asked...

I realize the tutorial is a work in progress and the vast amount of work required, kudos to everyone on OpenHAB. These comments are non-critical feedback in response to your feedback request.

I'm a pretty solid target audience for this tutorial and the suggested System Info binding looks like a great starting place...I sure can't figure out how to get it to do anything.

I'm someone who helps others with their tech, always have been. I'm not a software developer or professional tech. No prior experience with OpenHAB. A few steps ahead of a complete noob as far as Linus, terminal/shell stuff, navigating, etc. Very green but slightly familiar with Github, building complex apps. Old school.

• I suggest an entirely step-by-step approach to this tutorial, no 'overview' except a paragraph or two with links to conceptual stuff, then go right into a numbered list of steps. Possibly forked by platform as needed.

• The User Interfaces page, as an example, isn't helpful to the beginner tutorial. Tell the noob what to do, don't give theory or choices. Terms like Channels, Things, Bindings, Extensions, Rules, etc. are only going to be understood with exposure and something simple that ACTUALLY WORKS to build upon. Looking at something that is actually running is essential.

• Version 2 vs. 1 should be mentioned ONCE for clarity, then version 1 should never be mentioned again. Tutorial should state that it written for newcomers with no OpenHAB experience of any kind.

• It should be assumed that beginners have NO exposure to Github or the nuts and bolts of setting up anything beyond user-level Windows or Mac. If this is too low a bar for you, EXACTLY what the assumptions of a beginner's technical experience should be stated at the beginning. Since you cannot possibly know what level of expertise a beginner has, you have to spell it out. It may well be that a particular beginner has 8 out of 10 of your expectations - if you spell it out exactly, and provide a link to sources that will let a beginner fill in a gap before proceeding (in my case, Github was only slightly familiar and I struggled.

• I expect a LOT of otherwise tech-savvy but non-Linux types with new RPis are a big part of your potential user base. Plenty of smart and savvy folks to whom a terminal window and shell will be either entirely new or weak areas.

If I can be of any assistance in creating a tutorial, as a noob who's not entirely unfamiliar with the broad technologies, please let me know.

Background :

Have spent maybe 6 hours reviewing openhab website and github info,( just glanced at code). Ignored 1.X. Installed openHAB demo (2.0) on Mac, got Mosquitto up and running in two terminal windows. Demo didn't clarify what to do next.

So I grabbed old RPi, used OpenHABian to create a card image, worked great, MUCH easier than the first go round. (The hardest thing was finding the github link to download the OpenHABian file - noob!) So now I have a bare system running headless...the goal of this beginner tutorial sounds perfect for me. But I'm still looking at blank screens and mostly empty config files.

Good luck with your project!

Tim

[ThomDietrich]

Hey @grubstake, I'm sorry you didn't receive an answer till now. I was going to answer you as soon as I was certain what the next step regarding the tutorial should be. I was also seeing that problem and planned to write a completely new tutorial over the holidays. That did of course not play out. 🙃 The last few weeks didn't bless me with much spare time, leaving us with way too many tickets and way little new content.

Please have a look at this new development: https://community.openhab.org/t/setting-up-openhab2-from-scratch/20080 What do you think? Is this tutorial going in the direction you are looking for?

I would love to work with you on improvements to the documentation. Your message above shows me that you know how the user thinks and what's important. Additionally you have a nice writing style. As a non-native speaker I'm a bit handicapped in that area 🙌 Where would you like to change something? You could help Christian improve his tutorial or just as well write your own article. You could for example transfer the Transformations article from the 1.x wiki to the 2.0 documentation: http://docs.openhab.org/configuration/transform.html Another idea would be, that you could write a tutorial on a typical use case. I think these are very nice for users but sadly do lack in numbers. Have a look: Example 1, Example 2, Example 3, Example 4 Maybe you've got an interesting use case yourself?

Let me know what you think and I'm sure we will come up with something everybody can benefit from 😉

[grubstake]

Thanks for the reply.

I still can’t figure out if OpenHAB is intended to be a tool for developers or a user-friendly application for hobbyists & IOT enthusiasts that are NOT software developers. (If it’s intended only for developers, consider the following to be simply comments on what confused this particular hobbyist.)

I hope I'm not being overly critical, I am simply hoping this might help you. OpenHAB looks like a very sophisticated project which has had a tremendous amount of development. I fully realize that software development professionals are the best people to make projects like this work But sometimes devs have a hard time understanding the much narrower perspective of a “software user”.

Me? I'm pretty interested in using something like this to 'glue' together various IOT devices, and maybe get my geek on with some hands-on electronics like some sensors, etc. I'm not really, though, looking to get involved in a serious software development project, I'm more of a hobbyist and if I have to I’ll probably buy a commercial box or two.

I think there’s a pretty wide gap between what OpenHAB looks like as very nicely spelled out on the OpenHAB.org homepage and Introduction (one click from the homepage), and what it really is once you drill down and start looking into the details. The web presentation is very professional, very consumer-looking. It clearly defines the mission of OpenHAB, which looks at first glance like any downloadable app so far…

I can’t find anything about who OpenHAB is suitable for. Consumers? Developers? Hobbyists? What level of experience with software development, Linux, etc. is required? WHO IS THE TARGET USER? This information is really important for new users, as an ordinary user (non-developer/programmer/tech) is from what I can tell simply not going to be able to make use of OpenHAB.

Why do I say only a software developer could be comfortable with it?

An example: When I clicked the big Getting Started button on the OpehHAB.org home page I go to a "Downloads" page. System requirements look OK, download away (but I wonder why no version numbers or rev dates on the download page.) There is no mention of 1.x and 2.x So I clicked it, still not sure what versionI got: [download option 1]

This is the path I took to “get started”, it was not a good experience as a “consumer”. I ended up with a running Demo, which was not at all what I expected since it didn’t do anything and I could not understand most of the context for the rest of the content on the “Downloads” page.

I went back to the home page and clicked the “Github” tab on the home page and saw entirely different downloads and I realized was very definitely in the software developer world. OK, I can do that, but not very well… [download option 2]

I spent time in the Forums and realized this was serious geek-out project, not a ‘software install and tweak’ task. I decided my only hope was to ignore everything about 1.X and see if 2.X might be tolerable for me. [Download option 3]

I found the “OpenHABian” discussions and that was very helpful for me, so I was able to easily get a 2.x build running. But again, it doesn’t do anything without lots of configuration and all the topics on the forums seem to be by people who have a long history of running OpenHAB. Or they were as confused as I was. [download option 4]

The tutorial post you asked me to look at is along the same lines. "This tutorial is based on the snapshot Build #710 (Jan 9, 2017 4:56:47 PM), running on CentOS 6… releases are build by Jenkins in the CloudBees network (https://openhab.ci.cloudbees.com/job/openHAB-Distribution/) [Download option 5]

Anyway, of course there are many others. My point is, there are so many separate branches, plus v1 and v2, and I gather none of them are considered definitive official releases. That issue alone seems like too much for most people other than software professionals to take the leap.

Once I found the unfinished “Beginners Tutorial” I realized that there was a whole lot of work to be done even for someone like me with a fair bit of relevant software/hardware experience, and I thought I should give you some feedback.

I suggest some serious attention (starting at the home page) to filling in the gap between the high level description of the project and the numerous choices and tasks it will take to actually get the simplest test working.

Short term suggestions (in no particular order):

1. Have only ONE place on the website that links to a designated “recommended new user” release. (other than beta/development releases.)
2. Clean up all the confusion on the site between 1.x and 2.x Is 1.x deprecated and 2.x is now current? If so, are all the forums other than the v2 forum deprecated?
3. Make a working demo that starts up with operating bindings like “system info” running, and some other external data feed like weather, maybe even a handful of active bindings for the most popular commercial IOT devices so they can be auto-discovered and ONE UI. Describe each and every piece of what makes “system info” work. (i.e. things in the config files.) It’s a lot easier to understand a “machine” if it actually is operating when you are looking at it.
4. Fix the crazy confusion of the UIs creating invisible settings that aren’t in the config files but are in a separate database.
5. Recognize that only a tiny percentage of people interested in home automation have ever seen or used a Unix shell or written a line of code or know how to move around a non-GUI filesystem.
6. Describe the “user requirements” in addition to the “system requirements”. Clearly it’s not just a matter of a PC running JVM. Familiarity with non-GUI shell / terminal. Github. Linux basics, users/permissions, etc. Getting Started doesn’t even mention Raspberry Pi which I suspect is a major portion of your potential base.

As it is now, as a user, it looks like too much work to just take a test drive.

I'm not really sure if I can be of much help other than to clarify my previous comments here…and I’m probably just being annoying at this point!

Thanks,

Tim

[grubstake]

I had not seen much of the work I just noticed in docs.openhab.org. Those pages are not easily found when starting from openhab.org homepage.

Home page large 'button' for "Getting Started" and tab for "Downloads" appear to go to outdated information.

Suggest reviewing starting with Homepage and all directly linked pages. In particular,

-Consider changing "Getting Started" button link to http://docs.openhab.org/introduction.html -Consider changing "Downloads" tab link to http://docs.openhab.org/installation/index.html -Consider click path to docs.openhab.com from home page, and consolidating confusingly similar pages http://docs.openhab.org/introduction.html (v1?) and http://www.openhab.org/features/introduction.html (v2)

[kaikreuzer]

Home page large 'button' for "Getting Started" and tab for "Downloads" appear to go to outdated information.

They go to openHAB 1, which is currently still the official release. The links (and other parts of www.openhab.org) will be updated once openHAB 2 is officially released (due this month).

[M-ax-G]

Thanks Tim!! Very true, very constructive... And while nobody else says it: Thank you! for explaining what the initiated IMHO do not (seem to) get. I would love to help improve the doc or provide example, but I do not get the thing to work myself... which needs to happen firsts, before I can help others.

[psyciknz]

Regarding Tims post...as a 6 month Openhab 1 user, coming to to Openhab 2, point 4 was the one that seriously got to me.

Discovered items (discovered in paper UI) don't show up in the smart home designer, or in the familiar config files and vice versa. and there's a disconnect between what you see in the BasicUI in terms of discovered items and hand configured items - in that discovered items show up in basic ui with no effort. But a hand crafted sitemap has a specific URL that the user has to navigate to - in simplist terms this could be fixed by an automatic link from the BasicUI home page to list all the found sitemaps.

[Confectrician]

We are reworking the tutorial for openHAB 3 and have removed the complete existing Tutorial. Closing this issue therefore.