How to fill the knowledge gaps that arise when reading the documentation?

Setup, Configuration and Use Beginners
, , ,
1
  • Platform
    • Hardware: Raspberry Pi 3 Model B Plus Rev 1.3
    • Operating System: openhabian 5.10.103-v7+
    • OpenHAB Version: openHAB 3.3.0 - Release Build
    • Originating Issue: openhab documentation
  • Issue
    • Expected Behavior: If topics are described in the documentation, such as configuration parameters or tags for items, I would like to get all the necessary information or at least indications where further essential information can be found.
    • Actual Behavior: To give just two examples, I’ll describe my problem using the tags for items and the Google Assistant metadata for items.
      • When I build my semantic model, I am missing the information which tags are available for configuration. The list in the first screen of the semantic model documentation is unfortunately not complete.
      • When I want to configure the necessary metadata to use Google Assistant, I can see which configuration options are available, but a description of even the most important ones is missing. For example, what does the option “checkState=true/false” do?
    • Steps: (Steps to reproduce the issue)
      1. Read the documentation on a particular topic and count the question marks that arise in your mind. :wink:
  • What I have done so far
    • Reading the documentation
    • Reading the forum (here)
    • Searching for tutorials on the net
    • …

I know that this is a very generic problem. If someone can just give me a hint as to what reliable sources there are for the missing information from my examples, I would be greatly helped. Of course, any tips on where to find good additional documentation in general would also be greatly appreciated.

An additional helpful piece of information is that I try to configure as much as possible in text files, as I think this gives me a better understanding of my environment and text files are great to manage in Git.

2 Likes
2

Looks to me like you are already following the best practice: 1) Read docs, 2) If answer not in docs, search forum, 3) If answer not in forum, ask forum question.

It is a difficult thing to keep the docs fully current. Development on OH moves fairly rapidly and although devs are encouraged to add to the docs when they make changes, it doesn’t always make it to the top of their to-do list. For this reason, the docs rely on community members like you.

It is always helpful when users point out here in the forum or even better on the docs github page, what topics might be missing. Even better though, would be finding the answer to the question and then updating the docs yourself. Each doc page has a link at the bottom:
image
where you can submit your update to help fill in the gaps.

4 Likes
3

I am very pleased to notice, that this changes for a good amount of time now.
Also reviewers pay more attention in documentation too nowadays and check if (for example) a significant change is reflected in the documentation too during the contribution process.

5 Likes
4

Thank you, Justin and Jerome, for the responses.

Keeping in mind the principle of “working software over comprehensive documentation”, I must say that openhab’s documentation is already at a very high level.

Following Justin’s suggestion, I will be happy to actively contribute to the documentation improvement in the future.

This means that I am now looking for specific answers to my two examples.

  • Where to find the most complete lists of available tags for the semantic model?
    For this I have two ideas.
    First, you can of course try the corresponding dropdowns in the UI and copy the values from there.
    Better and possibly easier might be to take the enumerations from the code on Github. However, I’m not sure yet if they are easy to find there.
  • Where can I find some explanation of the configuration options in the metadata regarding Google Assistant integration?
    Here I am still completely in the dark.
1 Like
5

There’s actually a discussion about this right now.

2 Likes
6

I would start a new thread for each of your questions, with for instance, Google Assistant or semantic model in the title. Folks who know that aspect of openHAB will jump in. Once you figure it out, make a pull request to update docs.

3 Likes
7

Note: I understand that this topic is not about seeking the specific answers, and more about discussing the “user experience” of the documentation itself.

For me I would google openhab semantic csv

I never went to the actual openhab documentation. The CSV is great because it’s straight to the point for me. I just need the list without any accompanying textual description. It’s good as a reference.

For this I use Google too: openhab google assistant and I’ll go to the first result. The page is long and wordy (for me), so I would use Cmd+F to search for the word(s) I am looking for.

If you have specific questions about the google assistant tags, perhaps opening a new topic on the forum is a good idea.

3 Likes
8

Thank you, Jim. You were right that this topic was more about finding the right documentation than finding the specific answers to my examples. I hoped to find the answers myself once I know where to look for more documentation.

Your answers are nevertheless very welcome and I will see if and how I can improve the documentation with it.

I already knew the page for the documentation of the Google Assistant action. Unfortunately, I obviously hadn’t read it thoroughly enough. At the very end, for example, the checkState parameter is explained in detail. As for other item-specific parameters, I’m sure I’ll find answers as well.

9

So it may be a good idea to just link this file from the docs directly.
CSV is well readable directly from github, as it gets displayed as table.
Also we can’t get an outdated version, because github will alwas be up to date.

We just would have to add a note, that semantic tags may be not available yet in a stable environment,
when the list is viewed.

10

To bring in a different perspective, this is one reason why I push UI configurations so hard and flat out refuse to assist in text based config problems most of the time. For example:

But the list in the UI is complete and up to date for that version of OH. So you wouldn’t have had any questions in that case. Syntax errors are exceptionally difficult to make through the UI and often most of the properties and fields to fill out are fully described and documented in place in the UI.

I’ve gone down both paths of UI and text based configs and IMO it’s just not worth the hassle messing with text based configs. I’d rather spend my time solving home automation problem than syntax errors.

As for git, all configurations done through the UI get represented as plain text in the userdata folder which is very amenable to source control like git. I use git myself.

But even for those who insist on using a text based config, please use the UI as one of the places to look. The forms and options in the UI will almost always be up to date for your version of OH and the descriptions is often as good if not better than what you find in the docs.

For example, a fantastic way to discover the options available on a Thing or Channel config, is top create one in the UI and click over to the code tab. The names of the properties you see there will be the same stored in JSON will be the same you need to use in .things files.

Because in this case the semantic tags are tied to the OH version (unlike the GA metadata which updates independently) I would not be in favor of this approach. Is there no way we can pull in a specific version of the file with a release tag or release date?

Even if we add a note, the end user is left wondering which tags are valid and there’d be no indication of removed tags at all.

1 Like
11

Yes of course there is, i just didn’t think about putitng it in tagged.

I will have a look if we may use a tag straight forward or if we need to catch some edgecases.

4 Likes