Hi, first of all, great job on the new docs. I would like to make a suggestion to include some sort of diagram like this one below on the “Welcome to openhab - introduction” page. You can tell how awesome my graphics design skills are (not!), so hopefully someone can take the idea and make it so much better.
Having a little picture / diagram can do wonders to help people gain a better understanding of openhab’s architecture.
Please open an issue (if there isn’t one already).
My only quibble is it looks like openHAB is separate from Bindings Things Channels and Items.
I also think it would more appropriately be a part of the Concepts Overview page, not the introduction.
There was a version of a drawing like this that also included other important concepts and I think we should not ignore those too (persistence, sitemaps, Pages, rules).
Any drawings submitted to the docs need to be in DrawIO format so they can be edited by anyone.
Perhaps on the diagram it should say “OpenHAB Core”
At first, I also thought that it should go in the “Concepts Overview”, but I edited my post and changed it to “Introduction”. The main idea is that this diagram is the first thing that someone sees in the doc. Someone who wants to know what OpenHAB is. It is to grab their interest before they delved further into learning more details.
Or perhaps this diagram should go into Concepts Overview and another, simpler, more abstract idea diagram in the Introduction page?
In any case, the more “pretty pictures” the better. The Introduction page sorely needs pictures, and higher up on the page as the first thing people would see.
I have been an openhab user for almost 2 years, yet I don’t know what Equipment and Point are. Time to read the docs
My idea for such diagram is not to show everything about openhab’s capabilities. It is merely as a general “at a glance, what it is about” type of picture, for someone who has absolute zero knowledge about openhab, to grasp the very basic / essential idea about it. In this case, the simpler the better. In fact I think my initial diagram above is still too complicated.
Maybe, but even then all those things are defined by and live in the core. They are not separate. I’d either eliminate the block entirely or draw it all the way around the rest. Or if presented using a layered architecture, show it at the bottom of the layers.
But I don’t think this drawing does that. And you’ll have to add a bunch of text to explain the drawing anyway (drawings never exist without some text to explain it) and by the time you’ve done that half of the concepts section is now living in the introduction.
Were I to come to the openHAB page with no knowledge and the first thing I saw was that drawing, especially with all the additions that have been mentioned, I’d probably be put off thinking OH is too complicated if I’m expected to understand four layers of interaction of concepts before I even get started.
I would be in favor of that. But the more abstract diagram should show what openHAB does, not how it does it. In my world it’d be called an OV-1, Operational View-1. It shows how the people use the system or what the system does for people with little to nothing about how it does it.
It’s the semantic model which has been there since OH 2.5 but only used by HABot. It’s a structured way to Group and Tag your Items to inject additional meaning for the Items. MainUI uses this meaning heavily to organize your Items, automatically generate UI elements, etc.
Somewhere in there, we should convey the idea that it can “talk” to so many more other stuff, not just those mentioned on the image. I just grabbed a few icons that came to mind, but we can certainly make it more populated, e.g. somfy curtains, mitsubishi, daikin, tesla, aeotec (although yeah it’s just zwave), xiaomi, Ikea Tradfri (zigbee), knx, kodi, sonos, etc etc.
It is kind of pretty meaningless I guess, so if someone has a better idea, please do share. The general idea that I’m trying to show is that openhab is the central hub that can communicate, and control any and all of those things.
One step further, is to create some sort of animation, someone talks to Google Home or Alexa, the command goes to Openhab, then out to Philips hue, although this can already be done directly. Hm what’s a better example? Temperature sensor from xiaomi feeds data to openhab, then it sends command to airconditioner or fan…
What comes to mind is that most kickstarter pages are usually very good at grabbing your attention with the “wow” factor.
That’s the nature of such drawings. But remember, no drawing stands on it’s own. There is text that goes with it too. That’s where the meaning gets conveyed.
From a stylistic perspective, most of the details are too small on a small screen like a phone. But I think it’s closer to a drawing that grabs attention about what openHAB can do for you.
