Continued documentation discussion

As the OP came back with the progress of the primary question , I’d like to move the documentation discussion out of that thread.

Yes, the example was just that, an example, I was fairly sure google would find it , if the need arised.
You can find many more like that whrere the text is somethings in line of "Put this in your items file."
Write /etc/openhab2/items/astro.items
Or don’t. And say that Paper UI should be used, and never talk about the files .

More examples, I read this;
Open your browser web at http://localhost:8011, you should see the following screen:
but that is the wrong port, at least for me.
Again, more things could benefit from being decided and defined. Even if there is a technical possibility to it in other ways.

In my view the problem with curl, mkdir etc is not that you need to know about it, it is that makes the target environment unknown, and that in turn makes it hard to write documentation that is specific enough for beginners.
In my view, doc and first setup should be ‘almost’ fool proof and specific. Those who wants to walk their own path should be made to understand that they do exactly that.

If the learning curve is lowered OH will get more usage.

When I struggle to set up Tellstick, I’m not at a skill level (or confidence) to address doc issues.
and actually getting it to work my be another 5-10 steps with rules editing, site maps , configurations of items and things as well as rules. So I’m not even sure that what I perceive as a doc problem in fact is that when I encounter it.

As for sitemaps and item files
I had only one sitemap file, but still in the classic(?) gui i could see mine and one called Home.
(And it showed up in the phone IIRC)
In my view that’s a fault. I shouldn’t need to read doc to find out that there is an automagic default sitemap.
and the fact that is is called _default.sitemap instead of default.sitemap …
Things would be a lot easier for beginners if the _default.sitemap existed in the filesystem. and was called default …

Sitemaps and item files and rules are fairly free in namings, but that doesn’t hinder documentation to be specific.
point hard at default.sitemap and say that you can have others also, but that is an advanced topic.

I think OH could be great. In many ways it is.
But I think that the learning curve and the initial frustrations limits the widespread use.

My approach right now is to bring attention to issues,
If I can help out in other areas, point me in that direction.

2 Likes