Documenting openHAB 2

It’s a long story that goes back to when these forums were on the Google site. It looks like you found me though. For everyone else, I’m rkoshak on GitHub.

What happened was a mixup when we first started this forum. All the users were moved over as is (i.e. with their google usernames) and there was confusion about whether we needed to change our names immediately or if we had some time. By the time we all discovered we needed to do it right away or else lose our link to our old postings I had already written a few dozen postings and didn’t want to lose my connection to them. So I kept my name instead of changing it to what I would have (I usually go by paperrhino on forums like these).

With well over 1000 posts now I think I’m pretty well stuck.

I’ll be on a city trip to Prague over the weekend. That’s why I submitted the current version of the Linux/RaspberryPi installation article as PR
Would be great if one-two of you found the time to proof read and comment on it. Thanks!

@pr0f Welcome to the community! Which kind of work would you be interested in? For the article referenced above (mainly this one) it would be great to have an english native speaker proof reading. I’m german, so there might be a few errors in my languaging =)

1 Like

@ThomDietrich I’d be happy to proof read. I’m not sure I’ll be good for more than testing / proofreading until I get my head wrapped around the architecture of the tool. Heck, I’m still glassy eyed and drooling from trying to read general concepts from OH1 that I need to know to work the product! I’ll check out the link and read over it as I get time.

Glad to be of help.

First of all nice work and respect for all your hard work and effort.
@rlkoshak I’m looking forward for the documentation as you suggested.

I’m not sure but is there already documentation like you suggested in your post, and what this topic is … available to get started with.openHAB2.

At this moment I’m reading this
OH 2 Documentation - as guide line and more information - BOOK

But like already mentioned it is sometimes confusing … too much info.
So I’m really looking forward to the different levels of information for beginner till develloper.

@krismaussen, The official documentation page you should be looking at can be found at

1 Like

Hello everyone.

It has been a while since we discussed documentation related details here. That’s mainly because all discussions in this area shifted over to the GitHub Issue Tracker.

The upcoming release of openHAB 2.0 will certainly create a certain attention and openHAB doesn’t have to hide from that. Sadly many new users are scared away by the lack or the quality of the documentation state. This covers both technical documentation, binding READMEs as well as Tutorials and Examples.

With the feature freeze for openHAB 2.0 GA in place, it would be amazing if everyone reading this could consider solving at least one of the following issues! :wink:

  • All interesting issues: Link

  • Issues that can’t be solved because of an open question: Link

  • All issues just asking to write one small text from given information: Link

I want to mention a few users which I remember as being helpful and explaining to others or that have previously offered their help. Yes I did not forget about You! :wink:
No special order: @skatun @sihui @robin.muellerbady @jaydee73 @Branden_Smale @Tom_Still @UglyKidJoe @Max_G @erland_lestander @sam_calmes7 @RHINESEL @jlemmer @DocFraggle @elias_gabrielsson @rtvb @Dim @david @kubawolanin

Thank you all for helping others and giving back to this awesome community! :tada: :sunny: :monkey:


Has there been any discussion or thought about taking the repo at (“the Wiki”) and treating it as the git repo that it is, forking it or just making a gh-pages branch, git mv'ing each page of value into a convention that makes it useful for the overall documentation effort? I see it as a valuable goal to obsolete the wiki altogether for openHAB 2 users, and in the process fold its contents into the whole build process for Just curious on your thoughts about corralling all relevant documentation into the fewest possible places so it can appear happily in the end destination.

In the process, outdated installation and configuration instructions could be corrected, made consistent and streamlined, which is currently a source of frustration for many.

The old wiki would then be left in place with a big “we’ve moved” notice, and instructions for future edits in the new home. Interersted in your thoughts/opinions.

1 Like

I’d suggest there being a direct link to the documentation from the announcements section of the forum. It is quite difficult to find the link, especially for a new user. It needs to be found easily, and I believe new users probably find the forum before the documentation.

1 Like

I really haven’t used Github at all. Where do we actually contribute stuff? Say for example, a tutorial (issue #205) .

Do we write the tutorial in Github somewhere or do we do the tutorial here on the community forum and then make a comment in the Github thread?

I have the same challenge…
I started by installing jekyll on my windows pc (using Chocolatey) and I will proceed with the next steps based on:

More news soon :slight_smile:
(I think that I have to type up a more detailed “HowTo contribute to the documentation” before I start contributing content to it myself :))

@RHINESEL @Dim let me try to give a short tutorial:

For starters you could look out for smaller tasks where an existing article needs to be edited. All of the qick fix issues linked above (but also many others!) would be such issues (@RHINESEL I’ve removed the Tutorials ticket from that list).

Solving these tasks is very easy! You do not need Jekyll nor any deeper git knowledge. You can simply select one issue, open the related GitHub document, add the needed changes right in the online editor and propose these changes as a “Pull Request”. This process allows others to review every change and suggest further improvements. One special detail: According to this you need to “Signed-off-by”-mark your commits - please do not forget that.

If you want to add a new article (e.g. Tutorial page) it would be the easiest to discuss this in the related issue first. We can help with the needed steps there.

Looking forward to some great contributions :wink: Best! Thomas


Great starting point, thank you very much! I will try to contribute.

1 Like

Never realized there was an online editor. Gonna try it from my phone. I might be able to do more quick fixes that way while I’m on the go.

Here is a quick step-by-step I used to get going. I agree it is complicated but I do understand why these steps are necessary. These are taken from some notes I made and I really haven’t kept up. There may be errors or omissions. Note that this is really only necessary for major updates like the creation of a new document or major structural changes. For quick fixes use the online editor as @ThomDietrich described.

  1. You must have a GitHub account.

  2. Once logged in click on your icon in the upper right and select settings.

  3. If you have ssh set up (on windows this would be putty tools installed and pagent running with an ssh key loaded) add your ssh public key under SSH and GPG Keys. If not, generate a “Personal Access Token”. You need one or the other set up to interact with Github from the command line. On Windows you could also get the Github Client program but I have not had good experiences with it.

  4. Navigate to and press the “Fork” button at the top. This will give you your very own version to play with.

  5. Clone your Fork to your local machine.

  6. Add the original repo as the upstream with the command: git remote add upstream NOTE: use the http address if you did not upload an ssh key

  7. Checkout the gh-pages branch with the command: git checkout gh-pages

  8. Merge the changes from the upstream with your fork with the command: git merge upstream/gh-pages

  9. Create a new branch for the one issue you want to work on with the command: git checkout -b <name>

  10. Push the branch to github using the command git push origin docker

  11. Make your changes.

  12. As you go, add and commit changes with the commands git add . and git commit -m "message"

  13. When your changes are ready, go to the github page for your fork and create a PR. Make sure that the openhab/openhab-docs and appropriate branch is on the left and your new branch is selected on the right.

  14. Make sure to reference the Issue in your comment. Closes issue #XXX

  15. Additional commits can be made to the PR by making the changes locally to your branch and pushing the commits.

  16. you can work on more than one issue at a time by working on each one in a separate branch.

  17. Before creating a new branch, make sure to do steps 7 and 8 before creating a new branch to work on

Useful page:

When working with the docs, you can serve up the web pages as they will appear by changing directory to the source files and run jekyll serve and browse to http://localhost:4000/.

NOTE: The jekyll that came with Ubuntu as of a few months ago is not new enough and messes up the code blocks. Install the most recent version is possible.


Ok, I started slowly… will continue later on today and during the weekend

I made my first PR: for doc :

I hope that I did this correctly :slight_smile: I will contribute more stuff in the quick fixes soon also.

Edit: Oops… I just saw that @Benjy had already created a PR #240 for this document also :frowning: (i need to get more experience with github…)

1 Like

Oh no :disappointed_relieved: Maybe you can comment on his PR?
*teacher mode on* That’s why one normally first claims an Issue *teacher mode off* :blush:

Thanks for your help!!!

1 Like

Sorry Mr Dietrich :stuck_out_tongue:

But sorry @Dim ! I should have mentioned it!

1 Like

It was my bad. The PR info is online… I should have seen it :slight_smile:
I will comment on yours soon
For now, I got excited with something new here:

So I will tackle documentation in a bit :blush:

@ThomDietrich & @Benjy : I created a new PR for the windows installation instructions here: (view)

I also found a small bug with the service wrapper.

The java classpath in the default file that is created by the wrapper:install command is wrong (points to %KARAF_BASE% while it should be pointing to %KARAF_HOME%)

This is correct:*.jar

FYI karaf base and home should be the same by most of the time. Karaf home variable is used only when one karaf installation serves multiple processes. Wrapper script points to boot/main class which will not be present in children instances.
Even if its not used in OH better dont change it. :slight_smile:
// ok, after checking

OH2 actually uses that.