openHAB cloud related documentation improvements

[ThomDietrich]

Let's restart discussions on that topic @marziman @ShaunCurrier

For reference:

• One simple proposal by me: https://github.com/openhab/openhab-docs/issues/195
• Some questions: https://github.com/openhab/openhab-docs/issues/239
• @ShaunCurrier's extensive thread in the community https://community.openhab.org/t/improving-openhab-cloud-related-documentation/23714
• A nice step by step self hosting tutorial: https://community.openhab.org/t/setup-your-own-openhab-cloud-myopenhab-server-instance/24716

Already available in docs:

• A link to myopenhab in the menu next to http://docs.openhab.org/installation/index.html
• Mentioning of openhab-cloud and myopenhab.org in http://docs.openhab.org/installation/security.html#myopenhab-cloud-service
• The openhab Cloud Connector readme at http://docs.openhab.org/addons/io/openhabcloud/readme.html

What do you think is missing, where do you want to introduce enhancements? Which part would you like to work on? Do you think transferring ryandetzel's tutorial should be considered?

[marziman]

@ThomDietrich,

thanks mate for trying to coordinate this. At the moment we have some urgent this to fix and improve and therefore my and dans focus is somewhere else. I like the post of @ShaunCurrier, so we might tackle it soon. I need to think more deeper how to do this step by step. I was also starting to create a "OH cloud Security" chapter for the readme.

I will get back soon with some time reserved for docu improvement. The input of you guys will be the good base to improve it!

Br Mehmet

[ShaunCurrier]

Re-reading my too-long thread in the community, here's what I still believe could use some attention:

• The openHAB Cloud README.md is nowhere in the docs, but is truly part of the openHAB ecosystem, so I propose that it belongs there.
• The full workflow of joining a Cloud instance is not brought together anywhere. We have separate documentation about configuring the connector and configuring on the Cloud. Normally people will be doing these steps at the same time and we are forcing them to jump around.
• The myopenhab.org "Setup and Configuration" section glosses over the actual setup and configuration and jumps straight to utilization things like notifications, remote access, mobile, etc. I think the actual setup and config should be stronger represented here if we going to point to it as documentation. If we solved my second bullet here then that relieves this bullet.

I think these are the big ones. I proposed one scheme for addressing all this in the community thread, but I'm not married to that. It would probably be better to start smaller than that, actually. I also made miscellaneous other suggestions but those seem less important compared to what I've focused on here.

[ThomDietrich]

Hey Shaun, your suggestions in the community thread are all valuable. I'd agree to start small and come to them next. With that said I'd start with the buffer article #195 because it's the one part regarding openHAB cloud (e.g. myopenhab) every* new user will look at.

Regarding your other points, would it be sufficient to interlink the different articles stronger? I'm thinking of the typical "Continue with ..." link at the end of one article.

[marziman]

@ThomDietrich, @kaikreuzer, @ShaunCurrier,

I found myself lost in threads. I think we should clearly seperate myopenhab.org from openhab Cloud. Also in the Docu. The Cloud Connector is not tight to myopenhab.org and thats also a reason to not put it too close together.

I think a good way could be to extend the oh cloud Readme and extend it. I would do the following, so that you know which parts I tackle:

• Add Security chapter to OH Cloud, explaining the base Security concept (since this comes up frequently)
• Extend and Review the Step-By-Step Selfhosting tutorial, since there is already one for AWS this makes sense to be added to OH cloud instance setup in readme
• Add a Quick Start (Connector + Cloud + Config)

I can give feedback if I am done with this, but I ve some Reviews in the Pipeline which are high priority. I am looking into it at the Weekend.

BR mehmet