I’m starting this thread to have a conversation about what we need for documentation in OH 2. My goals with this conversation is to brainstorm and identify what needs to be done, what can be started now verses waiting for OH 2 to mature some more, and perhaps create a high level outline.
If this conversation belongs on the ESH forum in addition to/instead of here please let me know. I’ve really not kept up with OH 2 so if some of the topics/questions below have already been written and addressed I apologize.
Here are my initial thoughts. They are kind of random but hopefully will get some conversation going.
The wiki makes a great reference but is not very beginner friendly. Should we create a guide by example that walks users through basic OH concepts such as how Items work, interacting with rules, persistence, etc? The guide would include installation and work with the Demo (or some version of the demo). I imagine this being something like the Learn X the Hard Way books or The Java Tutorial and other similar tutorials. If I were to create an outline of such a document it would be (obviously not complete):
Installation
Linux
Windows
Mac
Other (I know someone got OH 1 working on FreeBSD)
Running OH
Linux
Windows
Mac
Other
Logging (where to find and view, configuring would be its own section in the Reference documentation)
A Tour of OH
Introduction to the parts and how they work. Kind of a beefed up version of the current wiki's landing page
The key is to introduce the major parts, what they are and what they do, and how they interact with each other, Very high level
Designer
How to get it
How to use it
Bindings
What is a binding
Types of bindings
Installing and configuring a binding
Link to reference listing all the bindings and the individual binding's documentation
Concrete example of steps to install and configure a bindings for the demo
Items
What is an Item
Types of Items
Particularly describe how some Items can be treated like others (e.g. Dimmer can act like a Switch)
Format of the .items file
Behavior of loading files (i.e. get rest to undef)
Groups and their uses
Labels
Icons
Concrete example for Items from the demo
Items definition best practices
Make a point of where to look for binding configs
Transformations
...
Sitemap
...
Persistence
I put persistence next as it is often ignored but vitally important
...
Rules
I think this will become the longest section
Don't forget to address JSR233 or other alternatives to the DSL that will be built into OH 2
Event driven development
Format and structure of rules
Difference between actions and posting sending things to items
Functions
Group.members manipulation and how it can help simplify your rules
How to figure out what to import
Working with Time
Working with Timers
Casting to appropriate types and when that is necessary
Working with Numbers
Working with States
Lambdas
...
Scripts
Mainly address the differences and how to use
Design Patterns and Best Practices with the Rules DSL
...
Troubleshooting
Use the forum as a reference and document the most common problems and how to correct them. For example, permissions for Exec and zwave, everyMinuteStrategy for rrd4j, etc.
The big takeaway for the guide is users who work through the guide will build up the demo files and fully explain every line of those demo files.
What format will the OH 2 documentation take? I believe I’ve seen postings indicating that OH 2 documentation will be checked into Git instead of being a publicly editable wiki like it is at present. Is this true? If so what are the plans for the existing wiki? Where should people go for to read and/or contribute to OH 2 documentation? Should we make all of this clear on the current wiki (e.g. “For OH 2 documentation see url”)? Does it make sense to stick to a wiki for the user’s guide or does it make more sense to make it more of a Document to emphasize that new users should work through it, not jump around like you would with the Reference.
I see the user guide, the reference guide, and the developer’s guide as all being separate “documents”, perhaps with links between them.
There have been several calls for more pictures in the wiki. If we separate the reference from the user’s guide I would recommend the pictures mainly be in the guide. Too many drawings and screen grabs in the reference can be more of a distraction than helpful.
I hope this is enough to get the conversation started. I look forward to hearing everyone’s thoughts.
I would like to see a section on why you should move to OH2, I get that its the next great thing, but this whole point and click stuff scares me. I have not tried OH2 yet, but from what people have talked about in the forum we loose a lot of the manual configuration that is in OH1. Has anyone thought about forking and continuing to develop 1.x.
I am as far from an expert on OH 2 as one can get. But my impression based
on what Kai and others have said is that your OH 1 config should work in
OH2 with only minor changes (e.g. Splitting up openhab.cfg). If that is
indeed the case i don’t see how manual configuration can be eliminated. OH
2 would have to support manual config of the same things you manually
configure now. So wouldnt the PaperUI be in addition to, not replacement
for manual?
That being said, a why to switch section does sound like a good idea. I do
not think it is clear what is different between the two unless you have
closely followed 2’s development.
That’s not true at all, Kai has said before that one of the main priorities is to ensure backwards compatibility. In theory, anything you can do in OH1 can be done in OH2 (minus any bugs/quirks).
The main end user benefit, at least in my experience (and this is my #1 reason for moving to OH2), is a much streamlined set up for devices that are able to be auto-discovered/configured. You also have the ability to add/remove bindings/extensions/services from the UI, and a UI that is more modern and up-to-date (as I think the OH1 UI/Classic UI is ugly).
There are other benefits too but these I would class as “nice to have” such as the dependency management from Karaf so that when you install a binding/extension/service it automatically installs the other bits that it needs to work.
However if you’re risk averse, or not usually an early adopter, I’d say go with the saying “if it ain’t broke, don’t fix it” and stick with OH1 for the time being.
Thanks @rlkoshak to get that started!
I also do not yet have a clear opinion on how the documentation should be handle best, but let me give you some facts:
On github the main entry point is moved from openhab/openhab to openhab/openhab-distro. openhab/openhab already now only contains the add-ons and the wiki is only kept as “legacy” documentation for the (currently still official) 1.x runtime.
On the “why to move”: Because 2.0 will simply be the next runtime release, there won’t be any 1.9. So the answer is the same on why people should move from 1.7 to 1.8: They don’t have to, but if they want new features and fixes, it is the only option. @rlkoshak and @danielwalters86 are right: You can continue using your 2.0 runtime exactly the same way as the 1.8 - you can keep your existing config files and you might only require minor adoptions. I had already started a page to keep track of such changes. After all, the MAIN change of 2.0 over 1.8 is that the codebase as moved to Eclipse and thus the namespace of the classes has changed. So it is really only an evolution and no revolution. The situation that there are problems with certain add-ons is mainly due to the disconnection of the 1.x maintainers with the changes in the runtime in the past two (!) years - this is what I am now trying to force with discontinuation of the 1.x runtime, so that required fixes are eventually done on the 1.x add-ons.
Back to the documentation: I agree that a split in tutorial / user reference / developer guide make sense. One thing to consider is that the code is distributed and thus will be the “sources” of the documentation. E.g. the documentation of the different add-ons is directly included within the bundles (see where the links go on this page). I introduced it this way because it has several advantages: The documentation is versioned together with the add-ons, i.e. a PR should always also directly contain the corresponding documentation changes. With the current wiki, this is out of sync and we do not have the chance to look up the documentation of a binding for an older release, which is bad.
Tutorial: This is something that already exists in a German version for openHAB 1, done using ReadTheDocs. I am not sure though, if we should rely on another 3rd-party service for this. I would actually prefer to have it auto generated through Jekyll and deployed it directly to the openhab.org website (which is also fed from a github repo). Some content for the tutorial is also likely to come from ESH (like e.g. some concepts), so we should make sure that we do not have to maintain to many things twice, but rather do “single sourcing”.
User reference: This will be specifically the aggregation of the add-on documentation from the different repos, so again, I think this must be an automated scripting and generation through Jekyll like the tutorial.
Developer docs: 90% of the content is likely to be identical to the ESH docs, so the content should imho be maintained at ESH. To adapt it (e.g. show another IDE setup page) and have it in the openHAB “style”, it again would make most sense to have an automatic script assembling the content and use Jekyll to do the proper HTML rendering.
Note that all this infrastructure has already been built for Eclipse SmartHome - it can be found in https://github.com/eclipse/smarthome/tree/master/docs. When running a Maven build within this folder, the documentation sources are assembled and Jekyll is called to use an HTML template for producing the website, which is then available at https://www.eclipse.org/smarthome/documentation/. I think it would make a lot of sense to use this infrastructure for openHAB as well (which was a goal when creating it for Eclipse SmartHome anyhow).
I like the idea of using Jekyll for the documentation pages. It lets us treat the docs more like code which I think is important.
One question I have though is what exactly is the difference between ESH and OH 2? My understanding from what I’ve read is that ESH is the specification and OH 2 is a reference implementation (similar to how Java EE is the Spec and Glassfish is the reference implementation). Is that correct? From a documentation perspective that would make a nice dividing to decide what is appropriate to document where.
Automating as much as possible for the reference documentation is a must. I also like making maintenance and upkeep of the binding’s documentation be the responsibility of the binding developer and making updated documentation be part of the PR review.
One thing that I would have found useful from a reference doc perspective, particularly when trying to figure out what packages to import to, for example, get access to things like SwitchItem and DecimalType. I’ve found when I’ve needed to use these classes in my rules I’ve had to search the GitHub repo to find them (until I memorized what is where). It may belong in the developer docs instead of reference but having a JavaDocs for core would have been helpful.
No, that’s not it! ESH is a framework and OH2 a solution built with it. You can read my blog where I tried to explain it.
As a result, most code of the core runtime and all the APIs that it defines are located in ESH, not OH2. Thus most developer documentation is likely to be located at ESH as well.
what packages to import to, for example, get access to things like SwitchItem and DecimalType
Luckily, there is no need for these imports anymore in openHAB 2
Well I clearly didn’t go back on the blog far enough. Thanks for the link. So basically ESH is much (but not all) of what we would call “core” on OH 1. And while ESH implements a lot of capabilities, by itself it doesn’t really do anything. OH 2 is an application built on top of ESH.
So any OH 2 developer documentation will really just need to discuss additions and modifications OH 2 makes to ESH. And even then only those additions and modifications that impacts a developer needs to be documented there.The user facing stuff would be documented in the user’s guide/tutorial.
I like it. I would suggest that focus be initially placed on bulleted points in a tree like structure. We can then build out the sections and points over time and provide more detail, context, etc., as well as periodically change the structure as feedback is integrated.
Ok, so we all agree that we like it - now it only must be done
With more on more functionality being added to OH2, I think it is now really time to get some better documentation out of the door (and to aggregate it to a single place).
Is any of you volunteering to work on the infrastructure? I don’t think that we need a Jekyll expert for it and we probably can re-use a lot from ESH. It would be gorgeous, if one of you could take the lead on this!
I so desperately want to take the lead on this but realistically, if I did, I would not be able to keep up with any sort release deadline. It would be far better if someone who can devote the time necessary to devote to it would take the lead. This isn’t something I can do from my phone during five minute breaks throughout the day which is how the vast majority of my postings to this forum have been made (sorry for the bad grammar and weird word substitutions).
However, if no one steps up, I will do what I can. It just won’t be fast. Jekyll does indeed look to be pretty easy to work with, particularly if you are used to a SW dev workflow.
I am also not able to keep up with any deadline and therefore we hardly ever set any deadlines -
I prefer to have things moving forward instead of creating schedules, which then cannot be met because nobody eventually does the work. Hence moving slowly is definitely better than stagnacy!
But let’s give the others a chance to step up - if they don’t, you have the job
I think from the time I have known you in this forum you would simply be the best for this task … the explanations you are giving in your posts are always extremely valuable and even more important: everybody is able to understand what you mean
So if you see a chance to spend your spare time for this: I will vote for you!
Note that the discussion is currently not about the content, but the technical infrastructure, which indeed cannot be done in 5minute breaks on a phone… I agree with you that @rikoshak is actually the better fit for working on the documentation content.
I didn’t mean to say that you are lacking the skills for the technical parts! Just wanted to express how important you will be for the content side of things afterwards as well
I thought we were still in the “waiting for somebody else to step up” phase
So I would say: You have the job, @rlkoshak - congratulations !
Start whenever you feel ready for it - and let me know whenever you have questions.
@rlkoshak I hope your family is feeling better again.
Do you already see and light at the end of the tunnel and could give us an estimate on when you might be able to start on this topic? I think having a structured documentation for openHAB 2 becomes more and more important.
!