Great effort. Lousy timing 
and
(As I understand it, cloudbee is being phased out)
I think most would prefer appl maintenance by apt-get or similar.
I also think that all doc should rely on one installation method.
Then doc can be clear on directories and file locations etc.
For a beginner is is a tremendeous difference between
place your rules in /etc/openhab2/rules/ compared to
place your rules in your rules directory.
But in all a greatly appreciated documentation.
The single distro started with the snapshot I used in the tutorial, so no problem there 
I agree on your apt approach, but on CentOS thatās not possible (because of yum instead of apt 
). But the setup is almost the same after the first installation
That is a challenge because a significant portion of OH users are running on a non-apt based OS (CentOS, Windows, OSX, even some FreeBSD) or containerized (e.g. Docker, Synology). We would be cutting off a third at least of all users if we restricted the docs to just the apt-get Linux installation in the instructions.
Ideas have been floated to make the docs a little dynamic where you check a box at the top with your install type and the paths and some instructions get tailored to that type of install but I think pretty much everyone would agree we should focus more on the content right now than cool features like that.
I think you are absolutely rightā¦ I had a similar experience; endless frustrationā¦almost 40 years in ITā¦ e.g. wrote a complete and secure online store software package (ASP), do PHP, C++, a bit of Python, but this openHAB thing has frustrated the hell out of meā¦ arriving at the same point (multiple times) of simply ditching this bloody thing.
ā¦ if it werenāt for the help of a few individuals (rlkoshak, Udo, shui, and others) I would have dumped this thing quick smart.
It has always puzzled me (and still does), that I could do so many things in other languages, but could not in OH.
However, I am still here; have overcome my frustrations; like what OH can do (it is brilliant compared to any other HA system), but not the way it needs to be āprogrammedā. I would say, it is like learning other languages; some pick-up a language in months, while others may study them for years and never reach a satisfactory level of proficiency.
When I started out with H(ome) A(utomation) I was in the process of owner-building a house, exploring the option of automating it, ending up with an architecture, where I am building hardware (based on Arduino), messaging (with MQTT), and control and display with OH. I am doing things in concert, which no other current system can do.
When I look at the money side, despite having wasted time āen massā, I am looking at 2,000 AUD (~`1,300 EUR) for something that could have cost me 10s of thousands.
What I suggest to you is:
What also needs to be remembered and understood: this is a free, open source run by a bunch of volunteers, not a commercial off the shelf productā¦ enthusiasts with a shared goal of producing a wonderful system. If you hate it, just walk awayā¦
There are only two options:
All yoursā¦ best of luck.
Thanks,
I couldnāt find the name yum in my head so I wrote āand similarā instead.
But honestly I donāt know if both installs have the same directory structure.
For a beginner I think wget, curl, mkdir and unzips etc should be avoided.
Basically anything that hinders clear documentation.
I think that anyone that writes doc for an addon or binding or such is also greatly
helped if we can nail some things on the wall, like folder structures.
( But also other small things like calling the default sitemap default.sitemap for instance )
Here is an example of less than perfect doc that I see in many places:
If you don't have a Tellstick Duo or the number of device events is less
than 1 every 10 minutes you should increate the max_idle:
tellstick:max_idle=600000
All Iām left with is: āIn which file???ā
Yes I can see that One methods was oversimplified. And I donāt know if yum packages uses the same physical directory structure.
2nd best (or desperate last) option could be to set env variables so doc could refer to $OH_CONF/rules or something like that.
Even if the env variables wasnāt used by the package itself.
Heck, they could probably just be defined in the doc.
Hey,
I know what you are trying to say, all the more funny I had to google for the quoted sentence. As you can see, writing a text others can follow is not as easy as it seems.
Let me state a few things:
openHAB is best run on a Linux system. Linux systems are great as dedicated servers. Thatās why most instructions expect a Linux system. It is possible to run openHAB on Windows! Itās just not as commonā¦
When using a Linux system, you need to know the Linux 101. As a Windows user you know how to do things the Windows way - As a Linux user you need to know about wget, mkdir, ls and find. Itās not pleasant but everyone can do it. Please check the very first paragraph after the table of content here: http://docs.openhab.org/installation/linux.html
Now, does that mean itās pointless to look into openHAB if you do not want to bother with Linux? Not necessarily. Thatās where things like openHABian come into play.
Another big issue seems to be the documentation question. āThe documentation is incompleteā, āFollowing a tutorial didnāt workā, āI read somewhere that I have to set max_idle, now my cat is illā. Yes of course, the situation on the documentation front is far from perfect. However, most of the time I see questions like these, the answers are repeating and repeating. Often it would just have been a matter of one search. All useful information - including thorough documentation, answered questions, binding usage hints and even hands-on tutorials - can be found en masse under docs and here in the community forum.
Lastly I want to say something without wanting to offend anybody. Itās easy and quick to ask questions but hard and time consuming to give answers. Often this is a one-sided deal and I very seldomly see anybody giving anything back. If the one before you would have improved the Tellstick article, we wouldnāt have this problem. If you were to invest a few minutes to help others here in the forum, the next one could already spend time improving the documentation. Thatās what I would be doing right now, if I had not seen this discussionā¦
openHAB is not an iPhone. Itās a complex diverse framework for home automation covering hundreds of technologies and devices. Dig into it, get to love it, grow on it.
@rlkoshak as for documentation for a beginner: Create a step-by-step guide to setting it up and getting it running. Things like the pressing ctrl+n in the designer, donāt assume the user knows where the config file is, Give a real example of a sitemap and then explain it.
Speaking of which, would anyone be willing to share their sitemap with me so I can learn from it?
Iām working on getting one light working the way I want and learning from that. I have basicui controlling it. with the following:
sitemap home label="Main Menu" {
Frame label="Hall" {
Switch item=hall_light label="On/Off"
Slider item=hall_light label="Dim/Brighten" switchSupport
}
}
Iām trying to add the dynamic icon support so that if I switch the light off the slider goes to zero and the lightbulb icon turns to and āoffā state.
I tried this:
sitemap home label="Main Menu" {
Frame label="Hall" {
Switch item=hall_light label="On/Off"
Slider item=hall_light label="Dim/Brighten" "MAP(en.map):%s" <dimmablelight> {channel="hue:0100:0017882eb162:2:brightness"} switchSupport
}
}
I think the biggest issue with the current documentation is that it assumes too much. It assumes that a user knows that the default sitemap should be named default.sitemap or that you have to go into the config and tell it to load whatever.sitemap by default. Itās little details like that which cause the most frustration for me. Once, someone answered that for me I was able to get things going. Now iām just working out proper syntax for controlling things the way I want.
But there is a problem right there. The ādefault sitemapā does not really matter. You can call your sitemap whatever you want and even create multiple. BasicUI or your smartphone client will prompt you to select the one you want to open. Setting the ādefaultā sitemap in Paper UI is a second step but thatās totally up to you.
Ok, Iāve got it working with 2 lights now. Iām trying to get it to show the percentage the light is at but I canāt get it to do that. Iāve read the docs and tried each one but not sure what iām doing wrong.
Also, sometimes the icon will update based on the percentage and sometimes it doesnāt.
Hereās my files:
.things
Bridge hue:bridge:1 [ipAddress="10.0.0.5", userName="xxxx"] {
0100 bulb1 [lightId="1"]
0100 bulb2 [lightId="2"]
}
.items
// Rooms
Group WH "Casa de Tomas" <house>
Group HL "Hall" <corridor> (WH)
Group BR "Bedroom" <bedroom_blue> (WH)
Dimmer bedroom_lamp "Bedroom Lamp" <slider> (BR, WH) {channel="hue:0100:1:bulb1:brightness"}
Dimmer hall_light "Hall Light" <slider> (HL, WH) {channel="hue:0100:1:bulb2:brightness"}
.sitemap
sitemap home label= "Main Menu" {
Frame label= "Hall" icon= corridor {
Slider item= hall_light label= "Hall Light is [%d %%]" switchSupport
}
Frame label="Bedroom" icon= bedroom_blue {
Slider item= bedroom_lamp label="Bedroom Lamp is [%d %% ]" switchSupport
}
}
Concerning the documentation: I found the installation documentation quite good (could be extended or clarified here and there, but generally it was good). But after the installation I was quite left alone. I would add (in the openhab2 configuration documentation) what can be configured where, the relation between OH1 and OH2 configuration, mix-and-match-ability, and what part of the OH1 configuration can be used, should be used and is not outdated.
Also an Example collection would be very helpful, as many of the āoldā examples do not work any more, mainly due to minor issues, but for a beginner that can be a deal-breaker.
I am travelling at the moment, but I will write a more comprehensive suggestion as soon as I am back.
Please do so.
These are good points. Waiting for the extended list.
Iāve found the BasicUI to update sometimes, when it feels like it. Iāve tried messing around with it to try and see what the problem is and came to the conclusion that it ājust doesnāt work properlyā.
Iām not overly concerned, as I only use openhab to interface all my stuff with Alexa. Hopefully one day someone will create a nice interface, then I might use it.
Regards the documentation, Iāve found it to be all over the place, unorganised, and a lot of it is out of date.
I tend to search these forums for answers, and usually find them!
I think the best (only?) use for openhab, is as an interface to Alexa or HomeKit.
My 2p 
Ouch! I and many others use openHab for a LOT more then just talk to Alexa or HomeKit. Most of us use openHab because we can integrate dozens of technologies and not be forced into one limited ecosystem. Yes, as a group we need to get better at documentation, but overall I find this community one of the best most helpful of all the other HA platforms out there. I see a lot of people on this thread saying lets just do things one way, but as has already be pointed out you would lose a good chunk of the base. I for one would NEVER run a Debian based system over RedHat and others have the opposite view. I know it sounds lame, but it really is our differences that make this project stronger.
Hey Nathan, I almost wanted to agree with you but then came āRedHatā 
Hahaha just kidding. You are totally right. Thatās exactly how it is
As I said before āopenHAB is not an iPhoneā.
Rainman quote: ādefinitely not an iPhoneā
I would propose as a definition: āa geekās tool to automate almost everything, but hopefully there will be a org.openhab.binding.wife in the futureā. And I am a geek! 
Sometimes we do need to laugh a bit!
Cheers,
George
As I guess Iām one of those
There is a difference between doings things only one way and at least documenting one way of doing it in a precise way.
For instance, Iām assuming that it makes very little difference to folder structure if you retrieve the package using apt or yum, If so, there is a lot of room left to be more precise, even if you drop those of that want to download the zip files by themselves and install the sw in a folder of their own choice.
Having one OS specific doc page that defines variables that are then used in the doc is another way:
For example:
RH: $CONFIG = /etc/somewhere/openhab2/ (example only)
non-pkg install: $CONFIG = /opt/openhab2/conf/ (replace /opt/openhab2 with you install folder)
windows $CONFIG = c:\programfiles\openhab2\conf ( example only) ```
and the in the doc it could say ```edit $CONFIG/sitemaps/_default.sitemap```
instead of saying ``` edit your default sitemap ```
( where did the underscore go?)
5-10 of those predefined locations would cover some 90% of your uses cases
I honestly don't think there is a big conflict between more precise doc and allowing people to do things in alternate ways.
And I think OH can move closer to iPhone without giving up the essentials of the good stuff. :stuck_out_tongue_winking_eye:Yes, integrate dozens of technologies and then control them from one system (like Alexa or HomeKit).
Hopefully in the near future, someone will write a pretty, usable UI for controlling openHAB, so then we have a third option.
Appleās HomeKit also does exactly what you describe, integrates dozens of technologies and makes them work together, however with one caveat; they have to be HomeKit approved.