Documenting openHAB 2

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:

  1. a set of three books for people using OpenHab: a users manual, a reference manual, a cookbook
  2. 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 : https://bipphilippe.gitbooks.io/openhab2-compendium/content/

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

Also, I want to add that I’ve already written a good percentage of the bullet points above as forum postings.

1 Like

hi @bipphilippe, @Kai, @rlkoshak,

somehow I didnt get notificatiins about this topic going on. Was busy learning my.openhab stuff…just saw the Jekyll is ready!

I like what @bipphilippe started with the gitbook and its a good base. But with the docu we should also focus on normal new users. A cookbook would be something for the advanced chapter, what can be done later.
I also would say to use a dedicated github project for the doc. Writing good code means also documentation, therefore we need a mechanism for the addons, where a lot comes from the community and with frequent changes.

Just some more notes from my side:

We should care extremly to Keep it simple. I dont know but my feeling says we should think more from an unexpirienced OH 2 user, who never used OH2 before. We might do it to much from Developer and Pro-User view at themoment. This comes by the fact, that I always find myself helping friends to set it up, even with all the docu.

I highly recommend only one starting point and that should be on the http://www.openhab.org site referencing or linking to http://docs.openhab.org as @Kai proposed. +1 from me here!
Then we could do it pyramidically …which means we start highfly and dig deeper more and more.

Catching up the ideas from your good work, we could also think about a
"OH in 5 minutes (or in a nutshell)" and a “Quick Start Guide” to avoid long long reading an failing in frustration.
A user might be more happy if he gets all up running with just reading little Quick start.

Since there might be users, who want to be up to speed with all quickly. Again pyramid way: The docu can become more detailed step by step.
I also want to mention that we have to smoothly integrate or combine ESH Docu for the advanced users and devs, since it is the base and the underlying base framework. This should be kept in mind by us, too.

@bipphilippe which chapter can I support you? I got a little lost. Just saw your inwork, done and to be done markers. Should I grab a “to be done”?

Iam setting up jekyll to get it running with the new docs github repo.

BR Mehmet

1 Like

@Kai great! Just got it up and running in 10 minutes. Iam ready with jekyll…looks pretty good!

Just need feedback from @bipphilippe and @rlkoshak to not work on already documented parts.
Let me know when you got the basic structure ready.

Thanks a lot…

Beyond what I’ve written in this thread pretty much everything I’ve written have to deal with aspects of rules and such and are forum postings anyway so will need some work anyway and many of those will end up going into the advanced guide anyway. In short, I don’t think you would pick anything that would duplicate what I’ve done.

From a priority perspective I think sections 1 and 2 should probably be first.

Sounds in general good to me. Yet, I am a bit worried that this makes 6 books (plus advanced versions from @rlkoshak?) and that it might be tricky on the long run to find the best place to document something (or to maintain the existing docs). In practice, many things do not clearly belong in the one or the other, but a bit everywhere.
Take “setting the logging level” as an example. This is relevant for users (to report bugs) and developers likewise, it will be mentioned in the reference (console commands) and the cookbook for sure - I would even think that it should be taught in the tutorial. So a small single feature needs to be described six times…?

Can I use the ZWave binding as an example in the first version of the documentation ?

Ok for me, but I think @rlkoshak has a point that something without hardware would be more suitable for people to actively try it out. I like the idea of using the demo packaging, which is actually meant to be a starting point for people to learn.
I don’t know how to best do the tutorial with the demo: Installing the demo right from the start is like handing out the solutions. So the tutorial should probably rather describe how to get to the demo packaging, so that if the user successfully follows all chapters, he would have built it by himself. Btw, I do not mind at all, if the demo package is heavily changed/enhanced - it was hardly touched in the past 6 years and it still very much resembles my house :wink:

Hm, how does this related to the suggested books from @bipphilippe? Is it meant to be the user tutorial? It feels a bit like a mix of all three books (which might not be bad, see my point above).

We should continue to emphasize we are talking about OH 2 so probably should always add the two when referencing OH 2.

No, I actually stopped doing so and am now only talking about the “openHAB Distribution” as this contains 1.x and 2.x add-ons likewise. It won’t be long and nobody will really care about the 1.x runtime anymore, while the 1.x add-ons are still in use. Once we switch the official documentation, there will be only the “one” openHAB and the 1.x runtime can be considered legacy (thus if you refer to it, you can mention the 1.x, but not the other way round).

I think the JSR233 stuff deserves discussion in the tutorial as first approaches to rules writing

Note that this is still work in progress for ESH. I hope @smerschjo is not too frustrated about my response times and will soon join in again on it.

Regards,
Kai

Well, even if I could have spend some time in the last months, it’s okay as I was and still am quiet busy myself. I will not have the time for it for at least another month.

But after that, as it seems that OH2 has made good progress, I can start the migration of my own setup and complete the missing parts for full (backwards) jsr support. But as I already said, this will take at least another month, before I can even think about starting with it.

2 Likes

In my mind:

  • explaining how to set the logging level, with the examples of the binding used in the manual, is part of the users manual as it is needed for troubleshooting
  • giving the extensive syntax is the the reference manual
  • there is nothing to put in the cooking book - in fact the cooking book will much more used for rules, scrips…

I would like to set the three books in this mind:

  • you can follow the users manual to setup your install and learn the basics;
  • the extensive description (as detailed syntax of log set up) is inside the reference manual in order to keep the users manual simple, light and focuses on learning the basics of OpenHab;
  • the cookbook is a set of recipes (a kind of “tricks” book), giving extensive exemples, again in order to keep the users manual simple, light and focuses on learning the basics of OpenHab

I am used to split “reference” and “recipes” in two separate books but this can be merged in one.
I will do so.

I propose to work on 2 bindings in the user’s manual:

  1. the system info binding - from the setup to the writing of a rule triggering on a hard drive availability for example
  2. the wave binding, from the setup to device inclusion

This should cover the complete scope of possibilities in term of kind of bindings and be progressive in terme of complexity for the user.

What do you thing of this idea.

@kay : The système info binding is documented as a 2.0 binding but listed in version 1.9 snapshot in the paper UI. Is the 2.0 soon available ?

Yes, you can start on any “to be done” chapter.
Be sure that your help will be greatly appreciated.

I don’t mind having them separately, if you have good experience with that and no concerns about doc duplication.
The good thing is probably, that many parts of the reference book can then be more easily generated and aggregated and wouldn’t be too mixed with manually written parts. @rlkoshak, what do you think about this split? Do your parts fit in there nicely?

I propose to work on 2 bindings in the user’s manual:

Sounds good to me, I think this indeed nicely covers many use cases and the system info binding is a neat feature.

Is the 2.0 soon available ?

You probably wanted to ask @Kai, not Kay ;-), so let me answer: YES, it it available since today, see here!.

To placate pedantic people like me, it’s spelled openHAB! :smiley:

3 Likes

Indeed a VERY important point - I also hate to see it misspelled, especially in official documentation!

I think there may be some things that may need some discussion to decide where they fit, but I think everything I’ve thought of so far has a place. A big challenge will be converting a bunch of the stuff I’ve written as answers to questions into something that fits into a book. But I think between the wiki and other postings on this forum we probably have about 70% of the reference guide written down somewhere.

I think we are narrowing down on the split and scope of the guides. I too am a little worried about duplication of writing. But if we keep the scope of the users manual tight and point at the reference guide for more information I think we can avoid most of that.

And I hate to harp on it, but I do think that if we use the Demo as our guide that will help us to narrow the scope of the user’s guide.

I am building my brand new install of OpenHAB 2 (I am an OpenHAB newbie : ).
I am creating the documentation while I am progressing in my understanding of OpenHAB.
This is my first goal.

I do not measure how far this is from documenting the Demo as I do not know what is inside the Demo itself.

@kai:
have an issue with the documentation site. When I click on Getting started / openHAB basics or Getting started /Installing OpenHAB, the menu does not expand (as it does with the Documentation/Concepts menu items for instance). I cannot figure why. Can you help me ?

This is important. I am going to check this before publication.