Hi,
I am setting up a brand new install of OpenHab 2 with HABmin 2 and the ZWave bindings, in order to replace Indigo.
Doing so, I had to read dozen of pages of posts, articles and FAQ, and did not find a complete documentation.
So, I decided to create one while I am setting up everything.
It is a work in progress that is accessible there on Gitbook.
Feel free to comment the work done !
Documenting OH 2 is something that is in drastic need. I’ve been assigned getting things started with documenting OH 2 by Kai and unfortunately I am not doing the job in a timely manner (stupid life gets in the way).
See this thread.
Clearly you have an interest and ability. Would you consider taking over that effort to move it forward?
hey @rlkoshak,
iam also not the biggest expert in OH2. BUT I ve set it up sooo many times and I had the same issue, with collecting data left and right.
Maybe we can put heads together how to bring this topic to speed?
Maybe we can make this together. Iam not a jekyll expert. But already documented alot of projects.
I cant say I will do all…but I can take over some parts and document my steps also.
We need to somehow put the infos together and create sth. like OH2 in 5minutes…or OH2 for dummies.
…what are your thoughts? Dont give up 
hello,
I can take over this effort at least for the next months.
I used Gitbook in order to open to everybody the possibility to participate to the book.
My role will be on 2 aspects:
Concerning Jekyll
I spent a few minutes on the Jekyll web site : Jekyll works with Markdown, which is good as Gitbook is also working with Markdown.
To my understanding, Jekyll is a solution to publish the documentation.
But Jekyll needs to be hosted somewhere.
Do we have Jekyll ready somewhere ?
Concerning the content
@rlkoshak : I read the conversation your linked to your answer. I am going to include your thoughts and create a table of content in order to set up the final goal.
I think I am more in the focus of a User’s manual, so far.
@MARZIMA : you can easily join Gitbook and propose additions to the document.
Concerning the platform
My experience is just on Macintosh.
Sincerely,
@bipphilippe and @MARZIMA
The the biggest hold up is getting the Jekyll builds as part of the maven builds for OH 2 and the OH Addons. Until we have that established there really is no place for the documentation to go to.
The intent is:
Documentation should go with the repo, so most of the documentation for the core of OH is actually already being hosted and created in the Eclipse SmartHome project. documentation for the core of OH 2 that is different (e.g. installation, differences caused by the use of karaf, additions) should go in the OH 2 core repo. Finally, the documentation for the addons should go with the addons repo. I think a user’s guide probably would go in the OH 2 core project.
The end goal is that the Jekyll markup would be “compiled” as part of the project build and ideally be submitted to the live website. Obviously a lot of details need to be worked out but that is @kai’s stated goal.
We want it to work just like the Eclipse SmartHome project so really this first step is taking what the ESH project has done and port it over to the OH 2 core and OH 2 addons repos.
The relevant repos are:
Eclipse SmartHome:
Use this as the template for what we need to do to get Jekyll setup
openHAB 2 Distro
This is the OH 2 Core repo where stuff like installation guide, user’s guide, etc would be documented.
openHAB 2
This is where much of the source code for OH 2 core that doesn’t come from ESH is hosted. The Jekyll framework should be added here but I’m not cure what documents would go here verses in the distro yet.
openHAB 2 Addons
This is where the specific addons documentation would go.
All three of these latter repos need a Jekyll project created and added to the maven builds.
This is the first step.
It really came down to me because I was the last person standing. But I really am struggling to find the time to make any progress on it and as @kai will tell you, we are in desperate need to get this set up so we can start to move forward on actually building the documents themselves. If either or both of you are able and willing to take this on and get it going it would be a great help to me and the rest of the OH community.
Hi!
@bipphilippe & @MARZIMA, thanks for joining the efforts here!
@rlkoshak Since you are indeed behind the schedule (not blaming you!), I just did some tries for the Jekyll infrastructure yesterday and I think with a few more hours spent on it, I can get that going for the start. I’d hope that I have that ready early next week.
So if you all will then concentrate on the structure and the content, that would be gorgeous.
Shall we proceed like this?
Ok for me.
Just let me know when the Jekyll infrastructure is ready (and how to access to it )
Sounds like a wonderful plan. I hate that I dropped the ball on this. Its so easy to find five minutes here and there to write forum postings from my phone (I’ve gotten better about the typos and weird autocorrect errors) but trying to code through a phone app is just not working.
sounds good. If you have jekyll ready give us a sign and we might organize structure and content.
we should arrange how to step into this…is that ok @bipphilippe?
… @rlkoshak, dont worry mate. You can allways join if you got time.
…documentation, the job is not the most sexy thing
It is easier to contribute to writing than the code right now. I can write on my phone during boring meetings and other down time periods. Coding not so much which has held me up on setting up Jekyll.
— sent from my phone 
I have added @rlkoshak ideas in the book I have started.
As proposed by @rlkoshak, I propose to create two set of books :
So my current work can be split in two books.
The first one is centered on OpenHab 2 and would have this Table of Content:
1 OpenHab basics
The second one covers the Z-Wave binding and HABmin:
1 Setup
The (done), (to be done) and (currently working on it) reflect today’s status.
I have updated the Table of Content of my current work to reflect that at :https://bipphilippe.gitbooks.io/openhab2-compendium/
Sincerely,
Just as a heads up that I am working on it: I have created a new repo https://github.com/openhab/openhab-docs, which uses eclipse/smarthome and openhab/openhab2-addons as git submodules, so that their content is directly accessible.
Github Pages automatically runs Jekyll on it and the result is automatically available on http://docs.openhab.org/.
I am still struggling with a few things, though. The menu does not expand yet and the symlinks do not seem to be working (despite the fact that they are working perfectl locally…).
I will continue on it tomorrow night, I only wanted to share some first results!
Great, @Kai.
On my side,
Ok, I again spent some hours on it, but struggled a lot.
I had to learn that Jekyll on Github Pages does not support symlinks (despite the fact that Jekyll DOES support them locally, so I only noticed after pushing the stuff to Github 
).
So in order to aggregate documentation (mainly of add-ons) from other repositories, I have now added a pom.xml which copies the required files from the submodule repos to their place in the documentation. We will have to set this up as a regular Maven build, which automatically commits the changes.
@bipphilippe The currentl documentation is what already existed in the openhab-distro repository. I don’t mind if you do heavy refactoring of it, just a few remarks from me:
Regards,
Kai
Some more progress: I am now automatically generating the menu, so that it contains all 2.x bindings. We can do the same for other addons - I think this is pretty cool, because it means that as soon as a new binding PR is merged, it will automatically appear in the documentation without any manual action.
Do you all think that it is ok to have a dedicated repo for the documentation? The alternative is to create the gh-pages branch in the openhab-distro repo, but I am a bit worried that this means that the check out of the distro also requires the check out of the submodules, which would unnecessarily blow up the distro check out.
This is fantastic stuff! @Kai, I noticed that http://docs.openhab.org/features/bindings.html is only showing a subset of available bindings, but if you click on one, the menu that appears on the left does have all of them.
Yes, this is still the content of the manually maintained page from https://github.com/openhab/openhab-distro/blob/master/docs/sources/addons.md.
This should also be restructured to auto-compile the full list. I didn’t do this yet, because we will also need to extract the binding description and maybe we should directly go for some more structured meta-data like an icon/logo/image, a category etc.
As discussed above, I cared for the technical infrastructure and hope for others to help on the content now
Hi,
I will work on the content and hopefully I will have a first result Tuesday night.
Ahh, that makes sense.
Wonderful progress! I like having the documentation in a separate repo. It lets the documentation team check out the and contribute without necessarily requiring a checkout of everything. However, I will paraphrase a comment made by @watou awhile back: “when making changes to the [documentation] one should check the changes against what the actual source code does.” I think this “rule” is more applicable to the reference documentation but we shouldn’t lose site of it in the tutorial/getting started.
Question: I probably have enough material between my postings, wiki examples, other people’s postings, etc to fill a book unto itself with examples and generic advice for the Rules DSL. Much of it seems appropriate for the tutorial but a lot of it seems a little advanced/complex for beginners (e.g. lambdas). Would this go into the reference documentation, go into the tutorial, or warrant a third section?