README! openHABIAN not on main download page!!

[bgilmer77]

Guys & @kaikreuzer - I think I spotted a critical problem for newbies.

Brief summary: If we are trying to get NOOBS to start with openHABIAN, then we should guide them there with our websites and documents. BUT - if you start at www.openhab.org, and click on "getting started" (a great thing for new people, by the way), then you are taken to the overview article, where you will, undoubtedly click on First-Time Setup. This takes you to the Beginner Tutorial which tells you how to install OH2. All good, except that it seems we really REALLY want NOOBS to start with openHABIAN.

If a NOOB goes to www.openhab.org and then clicks on downloads (being impatient and just wanting to "get on with it", then there is no discussion of openHABIAN on this page at all, no mention that this is the preferred starting point for NOOBS, etc.

To me, this seems like something that needs an urgent fix. WDYT? I am happy to put some time into this if you think this is important to solve.

BTW, yes, the whole beginner tutorial needs to be re-written, but I believe it is more important to think like a NOOB, and get the pages and navigation for them fixed first.

[Confectrician]

I think there are some more points to mention for the main homepage, but i don't know if this is the right place for it.

But topic related i can say, that i have to agree to your mentioned things.
That sounds at least a bit confusing, when i read it here.

[bgilmer77]

At the very least, I would recommend including it on the download page. But there is a bigger question.

Is it the policy of @kaikreuzer and @ThomDietrich that we are trying to have an easy "onboarding experience" for new users by directing them to openHABIAN as the preferred starting point/platform for them? If so, then it could really improve the adoption of OH, but we need to ensure that when NOOBS Google "home automation" or "openHAB", that they end up landing somewhere with pages that are specifically pointing them in the correct direction.

I would be very happy to try to put myself into the place of a new person coming to OH for the first time, and to develop a (hopefully short) list of changes that might really improve the experience for them, but I do not want to put the time into this if this is not really what we are trying to do.

[ThomDietrich]

Hey, this is a good topic, but (till now) the main page is under control of Kai, let's wait for @kaikreuzer to comment.

[bgilmer77]

Thanks @ThomDietrich. In my work with the Advanced Media Workflow Association, and with the Video Services Forum, in both cases, we have faced a challenge in getting people on board with our work - especially with the AMWA. Right now the Board of Directors of the AMWA is actively discussing what we can do to ease the "onboarding" experience. We have a number of APIs, and we have reference implementations. But as one of our colleagues said, no one implements from zero. Now in that case we are talking about integrating APIs into professional products for the television and film industries, but the point is still the same - what can we do to get people up and running more quickly.
We have a Director of Membership, and we also have a Developer Board Member, two different positions, both of whom are laser-focused on issues related to getting people up and running in our organization and using our "products" (We think of them as products, even if we are a non-profit trade association developing open APIs and opensource reference implementations.)
I must give a LOT of credit to @kaikreuzer and the whole openHAB community for what has been done here. But the fact remains that getting up and running with OH without giving up, especially in the first month or so is a real challenge. Remember - if new people in our community cannot demonstrate some moderate level of WAF (Wife Approval Factor) fairly quickly, they may bail on our implementation and go with a commercial solution (which we know subjects them to lock-in, lack of features, etc. in the long run). Speaking for myself, coming on board at about OH1.8, even though I have been a *NIX admin for many years, I felt like an idiot for several months until the larger picture of OH and how it works developed in my head.
SO...
The main point is that if we can actively direct people to openHABMIN for their first experience, we are much more likely to get them on board. Once they have a working installation, then they can always move to some other platform, or expand openHABMIN by digging into the documentation. But to make this work, we have to view the website, @kaikreuzer's blog, and the community, as places where we can actively promote this as THE preferred onboarding experience. I notice that @rlkoshak participates very actively in the community, so he could be another resource to help steer people in this direction, IF this is what @kaikreuzer wants to do.

[kaikreuzer]

Thanks @bgilmer77 for bringing this up, I fully agree that the onboarding process is important and the current "flow" far from being ideal.
Let me answer on the two different slightly topics:

1. Website: www.openhab.org is pretty outdated by now indeed and I have it on my to-do list to trigger a discussion about a relaunch and how the main page, the blog and the docs can be merged into something nicely integrated with each other. The past weeks have been pretty rough due to the release and I guess I won't make any steps forward on that before early January. But the "onboarding information" should definitely be one of the guiding themes for the website relaunch.

2. "openHABian as THE preferred onboarding experience": I absolutely agree that @ThomDietrich did a terrific work with openHABian and that it is by far the very best way for anyone that is planning to run openHAB on a Raspberry Pi or PINE64. But this is at the same time my concern: If someone comes across openHAB and wants to "quickly try it out": Isn't it so much easier to download a zip and run a start script on ANY OS that he might be using (Windows/Mac/Linux) instead of buying a raspberry pi and an SD card, flashing the card and waiting half an hour for a hopefully successful installation? What about the users that have a Synology NAS at home? Why should we bother them with openHABian, although they could simply install openHAB on their NAS by the click of a button? So my point is that openHAB was always meant to be not only vendor-agnostic, but also hardware-agnostic - there are simply many options to choose and not one is the right one for everyone. So while openHABian should be mentioned as a major option, I would not go as far as saying it is the preferred option.

[bgilmer77]

@kaikreuzer Yes, I thought about the point of having to buy a PI to get this working, and the fact that OH can run on many different platforms. So if someone is at Level 1, let's say, in their computer knowledge, then if they want to run OH on their Windoze machine or their MAC, then they should be able to do it.

But look at the case of someone who is at Level 0. They use computers, they use iOS or some other smartphone device, but when She Who Must Be Obeyed says, "why don't we have a smarthouse like the Smiths?", then offering a solution where one just buys a PI from Amazon, and in a few simple steps, they are up and running seems like a Very Good Thing to me.

I am not arguing against what you are saying about multi-platform; in fact I completely agree. Ultimately @kaikreuzer, this is your project, and this is where having someone who is the head of the project really helps. You set the tone, and as a member of the documentation team, I will do my best to implement it.

(FWIW, right now - I mean literally right now - I am TRYING to get openHABIAN loaded on my dev system. I have never run it, and given how important it appears to be, I want to start getting up to speed on it. How has the experience been so far?

GRRRRRRRRRRRR!!!!!!!!!!!! HORRIBLE!

Why in the world is this available in .xz format? My MAC running High Sierra cannot decompress this file. My Ubuntu 16.04LTS desktop does not understand this format. I absolutely will get it to work. But for the NOOB, will they quit before they even get a burnable image on their computer? Okay - deep breathing. It will all be okay ;-)

Back to our regular program.

[Confectrician]

Maybe we should consider something like a small beginner survey on a possible relaunched homepage then.
Some kind of "unsure how to start with openHAB? Answer 5 questions and we give you a hint!" thing.

• Which system are you running?
• Have you ever worked with a raspberry pi?
• ...

I think a maximum of 5 to 6 questions would be ok to give an advise based on the answers.
And the survey should be free to use of course.

If someone knows the self preferred way already, theres no need for the survey.
If someones unsure, he/she might find a guide helpful.

[bgilmer77]

How about a simple flow chart?

[kaikreuzer]

Why in the world is this available in .xz format? My MAC running High Sierra cannot decompress this

You actually should not decompress it at all. See the quick start guide:
"Write the image to your SD card (e.g. with Etcher, able to directly work with xz files)"

But right, I see that you see my point that a quick start that requires SD card flashing will ALWAYS be an issue for NOOBS.
I also think that we need to think about two different use cases: The first one (which I referred to above by simply unzipping and starting the distro) is for the people who just want to try it out and play with it (e.g. on their daily-use Windows notebook). The second is what people choose as a production system (they won't want to use their Windows notebook for that). Here we get into "hardware recommendation", which I want to avoid, but where we should lay out the different available options. So yes, a kind of flow chart could help, although it can easily become complex quickly...

[bgilmer77]

@kaikreuzer said, "You actually should not decompress it at all. See the quick start guide:
"Write the image to your SD card (e.g. with Etcher, able to directly work with xz files)".

Kai, I know I am new to the project, so please take my input as positive contributions - this is my intention.

I read the Quick Start Guide. Maybe I am too conservative, but I am hesitant to load new utilities on a machine unless I have had a chance to study them to see what they do. So, as someone who is pretty familiar with downloading images, and someone who has been working with RaspberryPIs for a while, I expected to be able to download the image and burn it to a microSD card using my usual dd= command. As you can tell from my frustration, things did not work out as expected.

IA NOOB would probably be just fine, since they would follow the instructions explicitly. But even if you assume you are dealing with someone with basic knowledge, if they have configured a PI before, they will be looking to do something similar to the general RasberryPI OS installation instructions, which means they would expect to unzip it and burn it. In the case of openHABIAN, it is my feeling that we will have the greatest adoption if this looks and feels like an image installation distributed by those guys.

My two cents. Feel free to burn before reading.

Sincerely,
Brad

[kaikreuzer]

All you are saying simply seems to confirm my view that a quick start that involves SD cards is likely to be a rough one...

[bgilmer77]

Yes - I agree.

Also - openHABIAN should be exactly like a software distribution from the RaspberryPI Foundation so that people who have figured out how to do it can do exactly what they normally do in order to install openHABIAN.

To sum up, the simplest solution to my initial point is to simply add a section on the download page for openHABIAN, and to have users who want to use openHABIAN do the same thing they do when they install NOOBS or Raspbian.

[ThomDietrich]

@bgilmer77 could you please move your concerns to the openHABian issue tracker? I don't want to start with counter-arguments here ;)

[bgilmer77]

Done - it is @ openhab/openhabian/#303.

FWIW, after hearing @kaikreuzer's thoughts, I agree that openHABIAN should not be the preferred first stop for NOOBS. However, I do think it should be easier for NOOBS to find it and get to the image download. Also, as I stated above, I would suggest that openHABIAN images be in the same format at RASPBIAN distributions so that people burn the image to an SD card in exactly the same way.

EOM
EOT(hread)

[ThomDietrich]

openHABian: Thanks. I'll get back to you there.

Regarding the actual issue: Remember that we already have http://docs.openhab.org/installation/index.html - The article just needs to be integrated in the new page in the right way.