I’d like to improve the openHAB Cloud-related documentation.
I just got through setting up myopenhab.org with my openHAB instance and am very impressed by openHAB Cloud. If I had known how easy it would be to set up, I would have done it a while ago. I do not see any official tutorials for setting it up and I also ran into some miscellaneous things that caused confusion. For this reason, I’d like to help improve the docs.
It seems that a minimum of these existing docs are involved:
- Main openHAB Cloud doc
- source: OpenHAB Cloud README.md
- Not built into docs.openhab.org?
- Covers how to install a Cloud instance
- Covers architecture of Cloud
- Walkthrough of running Cloud on Amazon EC2
- Main Cloud Connector doc
- source: Cloud Connector README.md
- built into docs.openhab.org here, but is extremely buried in the list of things in the IO doc page at docs.openhab.org > Add-ons > 3rd Party Integration and cannot be navigated to in the menu, as discussed in openhab-docs issue #344.
- Explains what Cloud can do for you
- Explains UUID and cloud secret
- No comprehensive tutorial on joining a Cloud instance and configuring openHAB and devices / notifications
- A reference in docs.openhab.org that OpenHAB Cloud is one way to secure remote access
- Found here
- One sentence on how Cloud secures remote access
- Suggests registering at myopenHAB.org
- Does not mention self-hosted Cloud
- Does not point to any official overall Cloud tutorial, which would be preferred
- A menu item in the main docs, Installation > myopenHAB, is visible, but not linkable here, just links to the myopenhab.org website and is not actually a doc (!)
- There’s no existing overall configuration tutorial
If I can get a maintainer to agree to my points of improvement, I’d love to work on them and create a PR. Here’s what I’d like to improve:
- High level restructuring of the documentation related to Cloud connections, featuring the following major components.
-
docs.openhab.org > Concepts > openHAB Cloud
- Cloud overview and explains relationships and distinctions of Cloud, Connector, and myopenhab.org.
- Explains the advantages of connecting openHAB to an openHAB Cloud instance, which is notifications or remote access + notifications.
- Probably only a few paragraphs needed here to begin with.
-
docs.openhab.org > Installation > Cloud Connector
- Would link to slightly improved version of existing Cloud Connector README.md and focus on installing the connector, but not setting up a connection.
-
docs.openhab.org > Installation > Self-Hosted openHAB Cloud
- Simply references the existing openHAB Cloud README.md
-
docs.openhab.org > Configuration > Cloud and myopenhab.org
- Focus on overall configuring of an openHAB instance’s connection to a Cloud instance, regardless of where those configuration steps need to happen - on the Cloud site, on the openHAB instance, or on a device. Tying this whole thing together is the big missing piece right now in my opinion.
- This would link to the Connector and Cloud install docs in the first paragraph to make sure those steps are already done before proceeding. (Eg. "This tutorial assumes you have already installed Cloud Connector on your openHAB instance (install steps here) and know which cloud instance you want to use (myopenhab.org or a self-hosted instance (install steps here).
-
docs.openhab.org > Concepts > openHAB Cloud
- Something about how users are handled in Cloud? (I’m not quite clear myself on how they are handled. User accounts are set up on the Cloud instance and are independent of everything else?)
- Improvements to the remote access security reference here:
- Focus on what the user wants to know if they considering Cloud for securing access
- Invite reader to docs.openhab.org > Concepts > openHAB Cloud for further reading
- Bonus points: What this guy is asking for in issue #239 of the openhab-docs project..
This is maybe a bit ambitious for me, but would be nice to at least move in this direction. Especially stubbing out and initial basic population of the improved structure mentioned in my first point seems important to helping users understand better and would reflect the importance of openHAB Cloud-related things as not just another add-on.
My questions to the expert maintainers:
- Is my basic theme here directionally correct?
- Would you anticipate the changes I’m proposing being accepted?
- Do you not like any specific points I have brought up?
- Did I miss some existing docs which I should know about?
- What is proper capitalization of “openHAB”? Seeing the initial “o” without capital seems wrong to me.
@ThomDietrich seems to be a guy who should see this post. Not sure who the others are.
Thanks for reading and thanks for this great software.