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 :
- a main book for OpenHab itself
- a set of books for the extension (one per binding for example)
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
- 1.1 What is OpenHab ? (to be done)
- 1.2 Things, items and Co (done)
- 1.3 Sitemap (currently working on it)
- 1.4 Rules and Scripting (currently working on it)
- 1.5 Bindings and other extensions (to be done)
2 Installing OpenHab - 2.1 Checking Java (done)
- 2.2 Installing OpenHab (done)
- 2.3 Installing the designer (currently working on it)
3 Working with OpenHab - 3.1 The different UIs (to be done)
- 3.2 Installing binding and other extensions (to be done)
- 3.3 Adding and configuring Things and Items (to be done)
- 3.4 Working with Sitemaps (to be done)
- 3.5 Working with Persistence (to be done)
- 3.6 Working with rules and scripts (to be done)
- 3.7 Looking to the logs (to be done)
4 Advanced OpenHab - 4.1 Advanced Rules and Scripts (to be done)
- âŠ
5 Tricks and troubleshooting (to be done)
The second one covers the Z-Wave binding and HABmin:
1 Setup
- 1.1 Installing the extensions (done)
- 1.2 Connecting to the Z-Wave controller (done)
2 Adding devices - 2.1 Adding a new Thing (done)
- 2.3 Configuring a Thing (done)
- 2.4 The Wave Database (to be done)
3 Other tools of Habmin - ⊠(to be done)
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,
3 Likes
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!
3 Likes
Great, @Kai.
On my side,
- I have reorganized the documentation files in Gitbook in order to ease the more from Gitbook to the new repo when it will be ready.
- I have read some documentation about Jekyll and Github pages in order to understand how they work.
- I have read the documentation that is already in the new repo in order to see where it fits in the table of content.
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:
- I have created two parts:
- one âtutorialâ/âgetting startedâ, which is the section for beginners to find their way - this should imho mainly be filled with the content you have started in your git book.
- one âreference documentationâ, which should nicely structure all the different features of openHAB to be a point of reference to look up stuff. This part gathers the content from the different repos and we should try to reuse as much as possible. For the general concepts, we should try to document as much as possible in Eclipse SmartHome and write that in a way that we can include it without changes in the openHAB documentation.
- Most binding readmes are still lacking the frontmatter header, so that Jekyll does not process them. I am wondering if we should add this header automatically when copying the files through Maven, instead of adding it to the sources directly.
- Note that you should not call any page âindex.mdâ, since the existing include files then fail (I couldnât make it work and gave up for now) - just as a word of warning.
- We can in future come up with better templates and more advanced layouting. I have for now copied over most of it from the Eclipse SmartHome documentation infrastructure in order to be compatible with the md files that exist there.
- All you need to do in order to work on the documentation is to check out https://github.com/openhab/openhab-docs and locally run âjekyll serveâ. You can then access your local work at http://localhost:4000/. Once you are done with changes, simply create a PR against the openhab-docs repository.
- Please note that I will introduce some changes wrt the setup of Things/Items through the Paper UI (see here). So better donât spend too much effort on this part before the changes become available.
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
1 Like
Hi,
I will work on the content and hopefully I will have a first result Tuesday night.
1 Like
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?
This is the reason why I moved the documentation of the bindings to the source code of the bindings - the very good thing is that a PR that changes code should also always adapt the documentation and when the PR gets merged, it is automatically in sync. This is a problem with the current wiki approach, where people have to track when their PR gets merged in order to quickly update the wiki as well then. So yes, I think this mainly applies to the reference docs and we should really try to keep these pages in the source code repos where applicable. Especially stuff that is not openHAB specific, but rather documents Eclipse SmartHome should be put in the Eclipse SmartHome repo directly.
Would this go into the reference documentation, go into the tutorial, or warrant a third section?
There is probably no right or wrong answer here - it depends. If you can structure stuff from it as a âwalk-throughâ, it can be done as advanced section of the tutorial(s); if it is rather useful for people coming across a problem and searching for a solution, it can go into the reference docs. Ideally, all aspects are covered in both sections.
Just my 2 cents, but feel free to do it the way you think itâs best 
Kai
I would propose a âCookbookâ in the idea of what OâReilly does (âJava CookBookâ).
If you agree, I am going to add an item for that in the top menu.
Regards,
Bernard
I would propose a âCookbookâ i
Is the idea something like a collection of mini-tutorials? We should just make sure that there are not too many entry points for the openHAB documentation, so that it becomes fuzzy where to find what.
Maybe we should start with some high level structure first. I was also wondering if we should more cleanly split user documentation from developer documentation, what do you think?
We also need to define how to integrate docs.openhab.org on www.openhab.org - at the moment, we have a getting started there as well - this should probably link in future to http://docs.openhab.org/tutorial/gettingstarted.html. And we should probably replace the âwikiâ link in the header with a âdocumentationâ link to docs.openhab.org - but there we then also need to include information about openHAB 1 and a link to its wiki.
This has been suggested before and I like the idea but think there are more important things to get documented first. Iâve also thought about a format similar to The Java Tutorial where you have a collection of âpathsâ which cover one major area made up of one or two page tutorials on how to do something. When you go through the whole path you get a complete understanding of the topic (e.g. go through the Java IO path and you will learn about all the java.io and java.nio classes and how/when to use them, but you could also jump straight to the java.io.ByteBuffer page if you just need to know about it).
But, as I hope is clear, this makes this type of dock somewhat between reference and tutorial.
For the Tutorial/Getting Started I think what we should do, after introducing some of the basic OH concepts, is to build up step by step the Demo and provide context and explanation for each piece. It has been a log time since Iâve looked at the Demo and donât know if OH 2 has a Demo yet, but I think structuring the tutorial in this way will help give it a structure, provide some much needed explanations to the Demo, and gives us something concrete to build upon as the Tutorial progresses.
Then the Cookbook, Path, or whatever we decide the structure should be can be an in appendix or Advanced Tutorial section or something like that.
This is key and one of the challenges Iâve had with the current OH 1 wiki structure. There are a lot of entry points and it is sometimes ambiguous where to look for certain information. We do need to avoid this. The nice thing with a structure like The Java Tutorial is that it builds up a hierarchy to limit the entry points.
I think it is reasonable to put a âLooking for openHAB 1 Documentation, click is hereâ link at the top of the entry point for the OH 2 documentation. Similarly, we could/should put a link on the main OH 1 wiki page pointing at the OH 2 Docs. It isnât ideal but Iâve seen it successfully done before.
However timing comes to mind. Do we make the OH 2 documentation the âprimaryâ on www.openhab.org now or do we wait until the official release of OH 2 to make the swap?
I think at the moment it is too early, so I would keep the OH1 wiki linked there. We should simply link to docs.openhab.org where ever we talk about openHAB 2, so I think this will get known and found easily. Iâll also soon remove the docs/sources folder from openhab-distro and rather point to docs.openhab.org from there.
Regarding cookbook: I agree with @rlkoshak that the tutorial should have most prio now. Iâll actually soon release a beta 3 and I would love to have some initial documentation ready for it then.
Introduction
My view of how to structure the documentation is pretty clear now.
Letâs me share it with you.
On the top menu of the documentation site, we have a place for one entry per book.
These books are:
- a set of three books for people using OpenHab: a users manual, a reference manual, a cookbook
- a set of three books for people wanting to develop with openhab: a developers guide, a developers reference manual, a developers cookbook.
The first set is my actual goal, so letâs look deeper in what they are for
Manual goals
The users manual
This is the manual you need to read to start with openHab.
The users manual covers the basic âhow-toâ, from the setup of Openhab until having covered all the mechanisms and concepts a user needs to know.
The reference manual
This is the companion book of the users manual. It gives extensive details where the users manual acts as an introduction.
The cookbook
This is the âtricksâ book.
Example
In the user manual, we will explain the structure of a sitemap file and what it is made for, we will give exemples
In the reference manual, we will give the extensive list of all the keywords and the syntax of a sitemap file
In the cookbook manuel, we will give some ready-to-use ârecipesâ as : how to insert a battery level information in a sitemap by using item groups instead of listing all the items
Table of content of the users manual
The actual table of content I have in mind is the following.
1 Introduction
- 1.1 What is OpenHab ?
- 1.2 Things, items and Co
- 1.3 Sitemap
- 1.4 Rules and Scripting
- 1.5 Bindings and other extensions
2 Installing OpenHab - 2.1 Checking Java
- 2.2 Installing OpenHab
- 2.3 Installing the designer
3 Working with OpenHab - 3.1 The different UIs
- 3.2 Installing binding and other extensions
- 3.3 Adding and configuring Things and Items
- 3.4 Working with Sitemaps
- 3.5 Working with Persistence
- 3.6 Working with rules and scripts
- 3.7 Looking to the logs
A book structure this way is available there : Introduction | openhab2-compendium
The table of content of the 2 other manuels will mirror the âworking with Open Habâ part 3.3 to 3.7.
Questions for you, @Kai and @rlkoshak
Can I use the ZWave binding as an example in the first version of the documentation ?
Pro: I am setting up openHab with ZWave, so it is easy to include that in my process
Cons : ZWave is perhaps not the most representative as there is also Habmin to be used with
Next stage
After your feed-back, I will use the content that is in the Gitbook book to publish it on the document site via a PRâŠ
Meantime, I continue to work inside the Gitbook book.
1 Like
Not anymore, see http://docs.openhab.org/features/bindings.html - the list of 2.0 bindings is now fully generated!
Also started with the UI overview: http://docs.openhab.org/features/uis.html
I donât see a problem using a specific binding in the Userâs Guide. It is one of the more popular bindings (based on the number of threads I see here). However, ideally I think it would be best to choose a binding that doesnât require special hardware for the tutorial. Users who do not have hardware yet, or have chosen some other type of hardware may be put off if the tutorial is mainly focused on zwave. It also makes it difficult for users to follow along with the tutorial with their own setup.
However, I also see that there will be some parts of the tutorial (e.g. automatic discovery) that may not be possible with a non-hardware required binding.
Also, the more I think about it the more I think that using a defined Demo config as the main (not necessarily only) example that is discussed throughout the tutorial will:
- help us ensure that the Demo example is complete
- provide a point of reference for the reader to refer to as they go through the tutorial, particularly given that very few will likely read the whole thing in order
- help guide us as we write the tutorial
- give new comers a relatively complete and fully described and explained integrated example to build upon
If we were to do that I think the table of contents could look something like this:
1 Introduction
1.1 What is openHAB 2?
* Origin and History
* Dependence on ESH
* Differences between OH 1 and OH 2 (very high level, not technical)
1.2 Architecture (maybe not here, maybe later)
* event driven
* message bus
* device abstraction
* initial framework to refer back to in rest of the tutorial
* Drawings! Visual map of the architecture which we can repeat with certain parts highlighted in
later sections to help those who are more visual than textual learners
1.3 Basic Concepts (may be better as 1.2.1?)
* Bindings and Addons
* Things and Items
* Sitemap
* Rules and Scripting
* Persistence
* NOTE: This section should be high level and the emphasis is to be on what they are for, what
they do, and how they work together, details go in Chapter 3. This is the introduction, it should
help orient but not yet bury the reader with detail.
1.4 Introduction to the Demo Config
* Paragraph or so explaining what the Demo config is for
NOTE: The rest of the sections need to be written with the assumption that this section has not been
read. Therefore the main focus here is to orient the user, not actually tell them how to do anything yet
2 Installation and Configuration
2.1 Prerequisites
* Oracle Java
* Hardware: RAM, CPU, etc.
2.2 Installation
* Include paragraph describing the two flavors of OH 2, offline and online
* How to install bindings for online mode (offline to be included in sections below)
2.2.1 Debian Linux (raspbian, Ubuntu, Mint, et al)
* apt-get install
* list of important files and folders locations
* paragraph about the fact that it is running under user openhab:openhab and potential problems
(e.g. needs to be added to dialout group or gpio group, issues with exec binding, etc). Not too
detailed or specific, just a taste.
* manually installing bindings
2.2.2 Linux Manual Install
* tar -xvf ...
* list of important files and folders locations
* how to set it up to start as a service
* optional additional steps the user may want to take (e.g. create openhab user, adding to
groups, etc)
* manually installing bindings
2.2.3 OS X
2.2.4 Windows
2.2.5 Designer Installation (if procedures are different per OS, move this section to 2.2.1,
2.2.2, 2.2.3, and 2.2.4)
2.3 openHAB 2 Configuration
* Location of config files
* OH settings (e.g. polling periods, security, etc)
* Logging settings
* Ports and how to change them
3 Working with openHAB 2
3.1 The Demo Config
* Where to get it
* Its structure and purpose
* A brief description of what it does (lighting, hvac, alarm sensors, etc)
* What bindings are required to run the demo
3.2 Using Designer
* Load a config
* Dealing with headless servers (SAMBA, etc)
* Navigating in Designer
* Important key combos (e.g. `<ctrl><space>, <ctrl><s>`, etc)
3.3 Adding and Configuring Things and Items
* syntax
* how to organize into multiple files
* naming schemes
* breakdown of the parts of an Item definition with full discussion of each part (labels
with %s syntax for state, dynamic icons, multiple bindings, the different Item types,
the different states, discussion about how, for example, a Color Item can receive
ON/OFF or Dimmer states and the implication of that). Where possible pull in (if it
can be done so automatically through Jekyll) or reference the documentation hosted
on ESH to avoid too much duplication of documentation.
* the concept of proxy Items
* manual verses auto-discovered
* Groups, when and why
* examples from the Demo with explanation (include at least a proxy item, a single
binding, an Item with multiple bindings, dynamic icons, etc) showing all the discussed
concepts together
3.4 Sitemaps
* syntax
* elements
* nesting
* dynamic
* override label and icon defined on Item, when you would want to do this and when you wouldn't
* advantages/disadvantages of using Groups on the sitemap
* webviews
* charts
* etc.
* examples from the demo of each of the above with explanation
3.5 Persistence
* What is it good for
* Format of configuration
* How to use Groups to make setting up persistence easier
* example from the Demo
* discussion of multi-tiered persistence (e.g. use MapDB for all Items for restoreOnStartup,
rrd4j for numerical Items that need to be charted and/or get access to recent historical data,
use MySQL for Items that need to be analyzed or you need more configurable charts)
3.6 Rules and Scripts
3.6.1 Rules DSL
* Event based, not state based
* Multi-threaded and implications of that
* Link Xtext syntax documentation with an explanation for where the Rules DSL is different
(e.g. no arrays, no classes, etc.)
* Rules syntax, naming rules, triggers, etc.
* Examples from the Demo
* Design Patterns (discussion, link to 4 for examples)
* Timers verses Thread::sleep
* locking
* lambdas (in the context of Timers and forEach, global lambdas probably goes in the
advanced guide), the main point is that the Timer lambda has a full copy of the rule's
context and you cannot use a var inside a forEach lambda.
* examples from the Demo with explanation (Theory of Operation)
* Actions discussion with discussion of built in actions
* Organizing rules files
* What needs to be imported? How to find it?
* How to use Java within the DSL? How to learn the syntax and apply Java examples
* Working with Numbers, BigDecimal, and primitives and doing math, how to round and
truncate floating point numbers
* Working with DateTime, now, and DateTimeItem
* Store as much state as possible in Items
* If your rules get too complex or ugly, consider a change in approach of a different engine
3.6.2 JSR233 Jython
* Same as 3.6.1 except for Jython
* advantages/disadvantages
3.6.3 JSR 233 JavaScript
* Same as 3.6.2
3.6.4 Debugging
* logging statements in rules
* which logs have what info
* how to turn on/off debug or trace logging
* how to interpret exceptions
* troubleshooting workflow (is the binding installed and running -> is the rule triggering ->
what line is failing, if trouble shooting a binding, move as much as possible into a rule to
get more feedback, etc)
* common problems and solutions
* How to ask for help on the forum: describe what you want OH to do, how you are trying to do
it, post Items, Rules, Sitemap, and Logs, and use the forum's code formatting feature when
posting code.
4 Examples
4.1 Design Patterns
* Proxy Items
* Loop and Group
* Time of Day/Year Tracking
4.2 Lighting Examples
4.3 HVAC Examples
4.4 Irrigation Examples
4.5 Alarm Examples
...
* Examples should take on a standardized form and include - all Items, rules, sitemap, and
persistence and bindings where applicable. There should be a description of what the example
does, the actual code, and then a Theory of Operation section which walks through the example's
event flow in English.
* There should be examples from all of the different rules engines that are built into OH 2, not just
the Rules DSL
* Maybe examples should be completely separate
* If possible at a minimum the Design Pattern examples should also be incorporated into the Demo
Notes:
-
Much of the bullet points above come from my experience with OH 1. Ignore anything that doesnât make sense for OH 2 and add anything I missed.
-
Persistence in the OH 1 documentation often gets ignored. I myself put off looking at it until long after I got my first working environment. I think this is a problem and want to make sure we treat persistence as a first class citizen on par with Rules and Sitemap.
-
I want to also make sure that we treat Designer as more than just optional. Section 3 should be presented with the assumption that the users are using Designer and include a section about how to use Designer.
-
We should continue to emphasize we are talking about OH 2 so probably should always add the two when referencing OH 2.
-
Iâd move the installation of bindings up to the installation section
-
I do not think it is a bad thing to be opinionated about certain things when explaining âbest practicesâ. For example, I think saying âyou should break up your Items into multiple files and organize your files by function rather than locationâ is perfectly appropriate to put in the guide because even though it is an opinion, there are strong arguments for why it is a good idea and it gives new users a good standard to start with which they can then ignore when they become more experienced.
-
I think the JSR233 stuff deserves discussion in the tutorial as first approaches to rules writing
-
Iâm open to moving many of the bullet points above to the advanced guide. Section 4 as well. The above is really just a brain dump.
-
There should be lots of links from the Tutorial to the advanced guide and reference documentation where applicable.
2 Likes