Closed tasosmich closed 7 years ago
We will look into that. Sounds like a docs-worthy topic. I would however not link the article to the Raspberry Pi as this should be totally platform unrelated.
@rkoshak would you be up to the task? I have honestly never touched that subject.
Note that a lot of input can be taken from https://my.openhab.org/docs.
Second note: my.openHAB from the openHAB UG will be terminated some time in the future and replaced by a version run by the openHAB Foundation. So you should not spend to much effort on such a tutorial for now; @digitaldan and @marziman might want to comment as well.
Assuming there is nothing special about the Raspberry Pi 3 aspect, I think I already wrote it as part of the Migration Tutorial. I made sure to cover it because the uuid and secret files are in a different location in OH 2.it should be ready to grab that section and turn it into a separate doc. It there is something different about running on the Pi, I won't be much help. I run on an old laptop.
Actually, shouldn't this be covered in the addon's readme instead of a separately maintained article? Or are we treating my.openhab separately?
hi @kaikreuzer, @rkoshak,
the documentation of the my.openhab binding is not related to Rpi3 or any hardware. I think this needs to be handled in the new upcoming my.openhab docu. The my.openhab binding functionality is meant to make the communication between my.oh cloud and oh possible. This relationship should be explained at the correct docu space. We might mention it at addons, but I think it makes sense to keep it close to the my.oh cloud explination, like already here at https://my.openhab.org/docs
@tasosmich: Is the actual docu above not enough? I think you mean a guide to put the secret and uidd to the right directories?
I think the big missing piece with the existing docs on my.openhab.org is they are tailored for OH 1.8 and not OH 2. Since the installation procedure is different for OH 2.0 and the uuid and secret files are in different locations it is causing confusion.
Also, when I come to my.openhab without knowing anything, it is not clear to me where the correct place to look for the correct way to install and configure it would be. The OH 1 wiki currently points to the my.openhab docs page, which makes some sense. Not knowing any better, I personally would browse down to the Binding docs for it to find them. This is partly because, just looking at the where and how of installation, there is nothing about it beyond the name that makes me think it is any different from any other binding.
So the question is, if we want these docs to be close the the OH 2 docs, where is the most appropriate place to put them?
I'm thinking Installation. Designer is already there and hopefully someone who is just coming to OH 2 will have at least seen the table of contents for the Installation articles and perhaps remember seeing the docs there. However, I also think that if I had forgotten it was there, I should be able to find it in the Bindings section as well. As an ignorant user, I would expect to see an entry in the table for each and every addon listed as a 2.0 addon in PaperUI/Karaf Console. The fact that my.openhab is missing form the list violates that expectation.
@marziman I am in the process of revising the docs menu. Which page do you want me to link for my.openhab? I wanted to go with https://github.com/openhab/openhab2-addons/tree/master/addons/io/org.openhab.io.myopenhab/README.md just as with all other addons ... but it doesn't exist. I guess it should? Even if it just introduces my.openHAB and then links to https://my.openhab.org/docs Would you be up to provide this file?
@ThomDietrich We are currently preparing the launch of a successor, which will be launched on Dec 15. It will come with a new bundle, the "openHAB Cloud Connector", see https://github.com/openhab/openhab2-addons/pull/1522. This PR contains a README.md, so that's the one that should be included in the Add-ons section (just like any other I/O addon). Additionally, we have documentation on how to setup your own openHAB Cloud service - its README.md could also be included at some good place in docs.openhab.org. Does this help?
Yes, everything's clear now. I'll track the PR and update later. For now I decided to add the external page here: https://github.com/openhab/openhab-docs/pull/148/commits/00188c96a840fdd5b644832a7acd1389c21ed4a4
Looks amazing by the way ;)
Yes, looks amazing!
@ThomDietrich as kai mentioned we are just in preparation to launch the opensource version. You should grab the docu of the openhabcloud binding (in review) + openhab-cloud docu (https://github.com/openhab/openhab-cloud/blob/master/README.md). Lets keep in touch to sync the docu parts!
I think, we must integrate the openHAB Cloud documentation in this openhab-doc (docs.openhab.org), or not? See: https://github.com/openhab/openhab-cloud/issues/5
Hey @cniweb if I got you right, you want to extend the document accessible here? That would be great! Remember, that it is a copy of this file.
@kaikreuzer there is also the file you mentioned earlier. Do we want to include these instructions? Also I'm a bit unhappy with the position. The article behind openHAB Cloud should not be located under "3rd Party Integration" but rather replace the direct link under "Installation". Wdyt?
From my point of view, we need a place at docs.openhab.org which should have a name like "Cloud/Backends" and not under Addons which brings together:
There could be all Cloud based integrations documented. Those requiring a backend to backend integration. The openHAB Cloud Connector docu is at the right place from my view. I miss a little the docu from the "cloud" view. I thought about extending the Readme of openHAB Cloud, but we were waiting to decide where to add it at docs.openhab.org
@ThomDietrich, @cniweb, @kaikreuzer:
Do you agree that we need to bring this smoothly together? (my.openhab.org/docs should be removed)
OH1: https://github.com/openhab/openhab/wiki/openHAB-Cloud-Connector
openHAB Cloud: https://github.com/openhab/openhab-cloud/blob/master/README.dm
Check out the menu entry "Installation -> myopenHAB", that's were I see the "openHAB Cloud Connector" article. I would suggest to extend this article with everything you got. The possibility to host your own instance of openHAB Cloud is (great of course but) only interesting to a few. There should be a headline in this article, informing users that self-hosting is possible, with a link to the openHAB Cloud article which could stay on GitHub. Alternatively we could link the article as a submenu entry of "myopenHAB".
Do you agree that we need to bring this smoothly together?
No, not at all. This split has been done deliberately as it is.
"Installation -> myopenHAB": I would suggest to extend this article with everything you got.
What would that be? What do you feel is missing in there?
The possibility to host your own instance of openHAB Cloud is (great of course but) only interesting to a few.
Exactly. This is why I only link in the docs to openhab-cloud, but not including its documentation as it will distract and confuse most users.
I would actually leave things as they are.
@ThomDietrich @kaikreuzer ,
the idea to bring it to docs.openhab.org was not so bad from point of view. But in fact it is myopenhab which needs guidance in the docs.openhab.org. For the openHAB Cloud I will extend the docu to have a full circle docu with "how to connect your device to the cloud".
I know @kaikreuzer that the spilt with OH1, OH2 etc is on purpose, but that doesnt mean that we wont confuse people with that. We have now multiple "connectors" and they can get lost.
@kaikreuzer I agree with the first few answers. I am still voting for this:
"Installation -> myopenHAB", that's were I see the "openHAB Cloud Connector" article.
Also:
I would suggest to extend this article with everything you got.
What would that be? What do you feel is missing in there?
Well I didn't look into it yet but at first sight I would like a diagram like this describing the functionality. Another thing that jumps out is the headline "UUID and Secret". What is that? Is that important to me? As an end user this headline doesn't tell me anything. Sure the text below describes that but still, I would call the headline "Instructions", "Setup" or "Connecting to the Cloud". In the table beneath the phrase "normal installation" is unclear, check here. Lastly I would suggest to put a "Host your own openHAB Cloud Instance" section to the bottom.
@marziman if I understood you right, you wanted to enhance the article?
@ThomDietrich @kaikreuzer ,
what you wrote is what I ve proposed before with "one place smoothly bringing all together". And I like your idea with "Host your own Instance" or "Connecting to the Cloud". I think it is not enough to just add docu to their certain places without having one place (I thought docs.openhab.org) where it comes together. Since it is a complex setup. If I go and add it to openHAB Cloud, people comming from that view might have the info, but the others comming from the OH Cloud connector docu dont have all infos. I feel at the moment it is too difficult and NOT thought from a user perspective. I always find myself in our docus and I often I got lost there. @kaikreuzer , whats the big problem with having one page smoothly explaining the chain in docs.openhab.org?
@ThomDietrich I will add an picture like that soon to the openHAB Cloud and some reference how to get the connector running with an own instance.
BR
I feel at the moment it is too difficult and NOT thought from a user perspective. I always find myself in our docus and I often I got lost there.
Could you elaborate? After spending hours to optimize the menu and actually showing it to friends to get their "user perspective" I'm a bit rattled by that statement...
So again @kaikreuzer , whats the big problem with having one page smoothly explaining the chain in docs.openhab.org?
It is information that <1% of users will be interested in and it might rather confuse 99% of users. That's why I like the current setup, which has the information people need to have about myopenhab at just the right places.
I am not against adding the README.md of openhab-cloud somewhere to the docs as well. But I think we do not have any category for such things yet. It is NOT about openHAB runtime (as almost all the rest), but about a new piece of software, the openHAB Cloud. I am not sure, where I would actually want to put that best, that's why I suggested to keep it in the repo itself for now. Note that we also have https://github.com/openhab/openhab-alexa still separate and potentially an Alexa custom skill as well soon. So I think we will have to see where to put those "cloud" stuff in general - and it imho should be clearly separated from the "normal" runtime stuff, since it is nothing that we recommend to the normal user to read, understand or use.
@kaikreuzer I have to ask again. Can I go forward with this? "Installation -> myopenHAB", that's were I see the "openHAB Cloud Connector" article. For me this seems like the correct position.
Regarding openHAB Cloud: I would second your suggestion to leave the document on github. Especially with the "Host your own Instance" section in place.
Regarding Alexa: In my opinion this is a "3rd Party Integration" topic and would thereby fit in just fine.
@kaikreuzer I have to ask again. Can I go forward with this? "Installation -> myopenHAB", that's were I see the "openHAB Cloud Connector" article. For me this seems like the correct position.
Hm, no, I don't agree. It currently points to www.myopenhab.org, which explains what you need to do for myopenHAB installation/setup/configuration: use connector bundle, configure your mobile apps, add notification actions to your rules, link IFTTT to it and use the Alexa skill. This is all relevant for users wanting to "install" and thus use myopenHAB.
The "openHAB Cloud Connector" article is available under Add-ons. It describes what you can configure in this add-on, just like for all the other add-ons. And this article is indifferent to whether you use this add-on for myopenHAB or for your own openHAB Cloud instance.
Regarding Alexa: In my opinion this is a "3rd Party Integration" topic and would thereby fit in just fine.
No, because this repo is again only relevant for self-hosting, i.e. the same situation as the openhab-cloud repo. The "Alexa for all" integration is covered on www.myopenhab.org (as mentioned above).
myopenHAB: I would argue differently as I don't like random menu entries throwing me onto other domains. There should be an article in between as a buffer. Be it the mentioned README or another one. :-1:
Alexa: I didn't know that openhab-alexa is about self-hosting. Then I'm of course on the same side as you. :+1:
@ThomDietrich: I meant the OH connectors and myopenhab.org, openHAB Cloud. It was not meant to say that the docu isnt good or you did a bad job. Sorry if it sounded like that. But still there is always room for improvements.
With user perspective I meant that at the moment, there a lot of docu sources regarding myopenhab. That is difficult to understand if you look what the people ask in the forum.
Guys I just shared my opinion. Iam fine with not putting it in..
@marziman I was not insulted or defensive, don't worry. I honestly wanted to get your feedback ;) Please share your thoughts, hopefully we can find a solution for everyone.
There should be an article in between as a buffer. Be it the mentioned README or another one.
Ok to copy the content of www.myopenhab.org to an intermediate page on docs.openhab.org as well. But it should not be the README.md of openhab-cloud, because this is some very different content and it should not be the documentation of the cloud connector bundle, because this is different content as well.
@kaikreuzer Where is the content of the site http://www.myopenhab.org/index.html @marziman and @ThomDietrich I also think that there must be two different documentations. Once for the connectors, as mentioned on the page already briefly, for OH1 and for OH2. Second, for the cloud itself, if you want to install it. In this case the installation on various platforms, such as Linux, Raspi, Docker, Windows, etc. can be divided.
@kaikreuzer Where is the content of the site http://www.myopenhab.org/index.html
Right here: https://github.com/openhabfoundation/myopenhab.github.io
could you please provide an analytic step-by-step guide for installing and configuring my.opnehab addon on raspberry pi 3.
Thank you in advance, Tasos