Initial experiences/difficulties/results with openHAB

documentation
beginners
Tags: #<Tag:0x00007f6ce53e5a68> #<Tag:0x00007f6ce53e5888>

(Joseph F. Karnicky) #1

Some general comments:
I am completely dependent on having a speech enabled home automation system.
Over the years, I put something together: x10 hardware, networked Windows computers, Java client and server programs, Dragon NaturallySpeaking and Vocola speech control.
Recently, it became obvious that if I was going to take advantage of the enormous capabilities of the Internet of things and mobile programming I would have to learn some new programming techniques.
After experimenting with other programs I tried openhab. Now, after a couple months of use I love the program. Even though I’m using only .1% of what openhab can do I have a very attractive, configurable, and powerful speech-enabled system that controls my new wireless devices (lights and switches) as well as my old x10 network, exactly the way I want.

Regarding ease-of-use:
Initially I was very frustrated. I had a lot of trouble understanding the documentation and nothing I tried worked without a lot of effort. BUT these problems were overcome with enormous support from the openhab community.
I think that the program is NOT intrinsically difficult to use but that the documentation needs lots of work. It’s clear that the developers of this program realize this but I’m not sure if you realize how tough it is to fix. Good documentation requires someone with a lot of experience at writing documentation. It also requires someone who is willing and able to put in the time on something that is not much fun to do.

Regarding open source:
Elsewhere in this forum there is a discussion of open source versus proprietary purchased software. I am not convinced that you get better software just because you paid for it (look at Windows). In any case, I didn’t find any commercial software that fits my needs.
On a personal note, there is so much trouble in the world these days-people in power acting out of greed and self-interest. Open source software, to me, is a very encouraging and uplifting idea that opposes these trends.

Overview:
My heartfelt thanks to the openhab developers and forum members. It’s a wonderful program.
Joe


(Lucky) #2

Hi Joe, first of all, I’m glad that you’re having a blast with openHAB!

It’s Open-Source. You can make changes to the documentation yourself.

I agree completely. Most organizations have their own dedicated technical writers/BSC/BAs.


(Holger OpenhabUser) #3

I fully agree with what Joe writes.
It took me also much much time to understand how OH works and what needs to be done to get a function realized.
The documentation is not so bad, but it does also not show all the pitfalls.
OH is so complex, that a newbie needs to invest significant time to understand and learn.
It is just not only an application where you teach a switch, put an icon on the screen and you’re done.
Without searching in the forum for examples, I was not able to finish a single task.
I don’t know how that could be managed better in documentation. Then really somebody has to write a book!


(Rich Koshak) #4

We completely realize this. But this is an opensource project. Everyone donates their time to work on what they want to work on. We cannot force someone to write good docs. We can’t hire someone who is a good technical writer to write the docs. We have done and continue to do what we can with the resources we have, i.e. the efforts of those who have volunteered to write/edit the docs.

If you are a technical writer or even if you are not we would welcome any contributions you could make to improve the docs. There are some rules and standards we have set but beyond violations of those we welcome anything you can provide. And those rules are mainly don’t repeat yourself (i.e. link to docs, don’t reproduce them) and outside of the installation docs keep the docs platform independent. And these rules are more to deal with the fact that we don’t have enough volunteers to update and keep in sync the same thing documented in multiple places.

I’m glad you have been successful getting started with OH. And don’t worry, even the most advanced of us only use maybe 10% of all of OH’s capabilities. The power is that everyone’s 10% tends to be different and OH can accomidate us all. :slight_smile:


(Joseph F. Karnicky) #5

I do have some experience in documenting software.
The amount of effort I can make assisting with the openhab documentation is very limited because of other commitments.
There are specific documentation subjects where I can contribute usefully.
To get me started:
Can someone give me pointers and/or descriptions of the steps that result in documentation pages ending up on the openhab website? I’m particularly interested in the beginner’s tutorial.
Regards,
Joe
PS [I’m only being semi-serious here->] The desirability of ease-of-use might be overrated. I suspect we all know the pleasure of getting something to work after a long struggle. Improving ease-of-use might be depriving people of that (dubious?) pleasure::wink: :.


(Rich Koshak) #6

The Docs are written using Markdown syntax and are developed and maintained in a separate github repo.

The process is pretty much the same as any other software repo. Changes are made and a PR submitted. The PR gets reviewed and merged. Once merged, the changes will be compiled into HTML and deployed to the website during the nightly builds.

For small simple changes, you can make the changes in browser. Just go to the file in github and press the pencil to open the file for editing. For more involved changes you will want to follow the github process:

  1. Open an issue
  2. Fork the openhab-docs repo
  3. Create a branch for your changes in your fork
  4. Clone your fork to a local workspace or work through the browser
  5. Make your changes
  6. Commit your changes
  7. On Github on your fork, generate the PR and reference the issue created in 1
  8. Be sure to sign off on your PR by adding “Signed off by My Real Name: myrealemail@server.com”

You can search for github tutorials for more detailed tutorials. I can’t emphasize the import of the branch enough. If you ever happen to work on more than one PR at a time, you will need branches to make updates to both.


(Joseph F. Karnicky) #7

Thanks for the info. I have to study the process you describe. (My professional programming ended about 25 years ago and involved 2 or 3 person projects-nothing as complicated as github).
In the meantime, here’s what I’m thinking:

what would improve the online documentation?

  1. some moderate changes to the beginner’s tutorial without rewriting the whole thing
  2. a concept overview describing the essential elements/philosophy of openhab
  3. more consistent documentation pages
  4. a document of the particular problems a beginning user of openhab on Windows might encounter

I think I could contribute most to items 1 or 4. I was hoping for some kind of a wiki. (Since I barely know enough to turn on a light using openHab, working on item 2 is out of the question.)

Regards, more later
Joe


(Rich Koshak) #8
  1. Absolutely. There are whole sections of the Beginner’s Tutorial missing.

  2. There is already a section in the User’s Guide discussing concepts. https://docs.openhab.org/concepts/index.html

  3. Consistent in what ways? Not arguing, just want clarification.

  4. That would make a great section in the Beginner’s Tutorial.


(Joseph F. Karnicky) #9

Thanks for the reply.
When I say “inconsistencies” I’m talking about inconsistency of presentation as well as inconsistency of description. This message just deals with presentation issues. Some of the suggestions which follow may seem very picky but this kind of thing can be extremely confusing to a beginner.

As an example of very good documentation, consider this page describing the Phillips Hue bindings:
https://docs.openhab.org/v2.1/addons/bindings/hue/readme.html


it is clear and easy to understand. In particular, note that the page contains a complete set of files (Things, Items, site map). There are enough examples so that you can figure out what’s going on in the code. You can modify the code for your own hue devices and try it out. And, for a beginner this is very important: the actual code that goes into the files is distinguished from the descriptive text by having a different background:

Compare this, for example, to the site map page of the beginner’s tutorial:
https://docs.openhab.org/tutorials/beginner/sitemap.html
After a few lines we find this:


I remember thinking, what kind of code is this? Where does it go?

A few lines further down there are a couple of file path names:


Again, it looks like code, again I wonder where these lines have to go in my program.

Further down there is an example of an Item definition which is the actual line of code that goes into the .items file. Perfect.

But then, about 12 lines down there is a discussion of the channel ID used in the Item definition.

The ID itself is presented against the shaded background and it has some kind of color coding which does not match the color coding in the Item definition above Again, very confusing-looks like a line of code but isn’t.


(Lucky) #10

I want to add… when writing documentation, make it concise and direct to the point. I always use bulleted/numbered lists whenever possible. Reading through paragraphs is just plain painful.