Improving openHAB Cloud-related documentation

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
    • 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).
  • 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:

  1. Is my basic theme here directionally correct?
  2. Would you anticipate the changes I’m proposing being accepted?
  3. Do you not like any specific points I have brought up?
  4. Did I miss some existing docs which I should know about?
  5. 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.

4 Likes
  1. I think you have a lot of good stuff here. Some of your suggestions about where certain things should be placed are probably worth some discussion (e.g I’m not certain there should be an article on openHAB Cloud in Concepts).

  2. After discussion, I see no reason why they wouldn’t be. I’m not sure whether this would be best broken up into multiple PRs or one big one.

  3. I think a discussion needs to be had over how we want to treat openHAB Cloud structurally in the docs. See below for my initial take on things.

  4. The myopenhab docs. The Cloud Connector works with both.

  5. The initial “o” is always lower case, even when “openHAB” starts a sentence.

Some of my initial thoughts. Note, they are just my opinions and do not represent anything official. Thom and Kai will have more official thoughts.

Hurray!

A Tutorial Posting in the Tutorials and Examples section of the Forum would be a most welcome first step. You will notice many parts of the official docs got their start there. It is a good way to get the content out fast, get it reviewed, and generate discussion about improvements.

The openHAB Cloud is a strange beast. It was only open sourced a few months ago and it has always had a somewhat separate relationship with openHAB proper. I don’t mean that the organizations are separate, just that Cloud is treated somewhat as a side project/capability that strongly technical users who do not want to use myopenhab.org can to host their own openHAB Cloud. The recommended approach for non-technical users is to use myopenhab.org, which is an openHAB Foundation hosted instance of openHAB Cloud.

Depending on what is decided as to how to/whether to integrate the main doc with the openHAB Docs, the Issue for these changes would go on the openHAB Cloud GitHub. Then openhab-docs will pull the changes from there.

Just Amazon? Should Azure, Google, et al be covered as well?

What if I want to host it on my own network because I don’t want to depend on any cloud service?

Cloud Connector is an add-on like any other. I think there are a lot of discussions needed to treat it as something “special” in the docs. Not only because it actually adds some complications to how that part of the docs are built but also because I personally feel uncomfortable making special exceptions as it sets a bad precedence.

Now I strongly would support adding a link to the Cloud Connector from any document that describes the installation and configuration of openHAB Cloud (as well as from the myopenhab doc). Personally, I would find that more useful anyway.

Actually, there is. docs.openhab.org > Installation > myopenHAB Now one could argue whether that doc is adequate or whether it is in the right location. But the information is there and the only difference should one would use the URL of their Cloud instance instead of myopenhab.org.

The “configuring openHAB” part is covered in the Cloud Connector README which is the linked to under “Setup and Configuration”.

I would say in addition to, not preferred. The vast majority of openHAB users should use myopenHAB, not spinning up their own instance of openHAB Cloud. I do agree, there should be either in this document or linked to from this document an end to end tutorial for setting up one’s own instance. But given what I said above, I do not think setting up one’s own Cloud should not be given prominence over using myopenHAB.

If you read it you will see that it is. Instructions for how to configure openHAB to connect to myopenhab.org either exist within that page or are linked to from that page. We can argue as to whether it is complete or adequate, but it is there.

I could see having a full tutorial in the tutorials section. Either split up like the Beginner tutorial or one big doc like the migration tutorial.

Create some issues. I can’t see anyone refusing improvements to the docs.

I personally do not thing Cloud belongs here. To quote the saying “one of these is not like the others.” Cloud is so unlike the other topics in that section I simply do not see it belonging there. In fact, I see it as causing confusion more than anything. Also, I don’t think Cloud should be given such a position of prominence.

Cloud Connector is an add-on like any other. It is installed like any other. However, I do notice that the only place that installation seems to be documented in the Beginner’s tutorial. So I would instead recommend adding a section to the Add-ons doc describing how to install an add-on. The readmes for individual add-ons should not document the installation process.

We can do one better and pull the README over. It may not be self-evident, but the bulk of the openHAB docs are actually pulled from other repositories. I definitely agree this is a good place to put this information.

There was a lot of discussions when myopenhab.org first started and before that for the my.openhab.org service and it was decided that this link would point to the main home page for the service instead of having its own doc.

One of the main mantras of OH documentation is DRY (Don’t Repeat Yourself).

I’m getting an error when I try to visit https://myopenhab.org/docs:
Cannot GET /docs

Not sure what you mean by “The Cloud Connector works with both.”

I will do that.

Still, why not have an openHAB Cloud doc in docs.openhab.org, albeit with proper warnings that it’s not for non-technical users?

Sorry, I probably confused you. In the section of my post that you’re referring to, I was listing the current state of the particular doc, not changes I want to make. It already includes an amazon walkthrough, for example.

From a technical standpoint, yes it is an add-on like any other. But what makes it special is that many users should be setting it up by default if they want it, and the docs do not currently help them even see that it’s a possibility. Instead, they’re left to peruse the forums and stumble across it. I could see leaving the doc in its current place (to respect it’s technical position), but pointing to it from some more central tutorial to respect its standing as the default way to access openHAB remotely.

Shoot, I missed that. I was confused by clicking the link and finding myself outside of the docs. Might be best to build a duplicate of this tutorial inside the docs so that the user is not jarred by being pushed to another site where the most immediate thing on the page is not the tutorial they expected.

Agree completely.

The material I’m proposing (how various Cloud stuff relates) is a “concept,” but I can see your point. It’s not a key openHAB concept like the concepts that are already in that category. Maybe instead this purpose could be covered at the top of some overall tutorial.

Does DRY exclude us from expressing information in two different places where people might expect to find it? Surely this can be done in a clean way with references back to a single source of the information. My argument against just linking to myopenhab.org is that I’m expecting to see install instructions immediately (since that’s the link I clicked), and instead the install instructions are a few paragraphs down the page. It sounds small, but I think this interrupts people’s flow and is confusing. It forces me out of the mindset of “how to I get my cloud connection running” and into “where is the information about how to get my cloud connection running.” Subtle, but important. I think this could be avoided and everyone pleased if we would simply reference and build the “Setup and Configuration” instructions from www.myopenhab.org into the docs and found in the Install menu.

Anyway, lots of ideas floating around here, one clear thing that seems to be in agreement is the need for a comprehensive tutorial. I’ll start there and make a topic in the community with what I come up with.

The docs are the main page.

https://myopenhab.org

Cloud Connector works with both a self hosted openHAB Cloud and myopenhab.org.

Not to be too cynical but a user in a hurry never reads the warnings. From a human factors perspective, because things at the top, things that are larger, and things that are prominent and set apart will take precedence over other parts regardless of what the text says.

There was an argument to do just that (i.e. put the openHAB Cloud doc in docs.openhab.org (can’t find it right now) and I think the maintainers decided they wanted to keep it separate. I don’t remember the exact reason. Personally I’d like to see it part of the main docs.

Right now it is linked to from the myopenHAB article under Installation (article is somewhat of a misnomer as that is a link to the myopenhab.org page). The myopenhab.org link also exists on the Security & Remote Access page.

I’m not sure if a direct link to the Cloud Connector is appropriate there as the users need to create a login and follow the instructions on the myopenHAB site first anyway.

Any article that talks about setting up the openHAB Cloud should also include a link to the Cloud Connector add-on.

And many users should be setting up MQTT, zwave, and Habmin by default…

I can see an argument for maybe making myopenHAB be first in that subsection of the Installation menu and adding an openHAB Cloud link to that section. And I already expect a direct link to the Cloud Connector from those articles. I’m still not convinced that it should be listed in the top level menus.

I also already concede that the myopenhab.org main/page probably needs to be beefed up.

I agree. It was discussed. It was rejected.

A “Install and Configure openHAB Cloud” tutorial perhaps… :wink:

If at all possible it is better to link to one central place for the information. The problem is the docs are being written and maintained haphazardly by a relatively small (but growing) cadre of volunteers. The likelihood that both locations where the same information is presenting being updated when a change is made that required updated documentation is near 0%.

I agree it results is more jumping around than should be necessary and is probably less than ideal from the user’s perspective. But inconsistent information in the docs is even worse. By studiously applying DRY we can at least have a reasonable chance at having consistent docs.

I completely agree but we lost that argument a few months ago. I don’t know that we fought it really hard so maybe you can reopen the case for having a separate installation page, even if it isn’t hosted on the openHAB docs site.

@scurrier03 and @rlkoshak,

hereis maybe one of the maintainers you asked for.
I ve created the readme doc and AWS howto.
I agree, we can extend the docu.
But we should keep the docu style intact. We also need to balance how much to document, since we shouldnt over engineer it.
Example Tutorials could help, but need little thought where to place it.

I will re read your post history here. At the moment dan and me have to focus on some topics at oh cloud. After that, I can support and we could tackle or structure this more?

Also interesting, how I missed this topic :slight_smile:

Br Mehmet

1 Like

Just wanted to let everyone know I haven’t lost track of this, just was
waiting for all input since others wanted to chime in. I’m reading up
what’s going on now.

1 Like