See this post!
Just a heads up guys. Iām about to be out of the country with spotty Internet for the next two weeks. Iāll still be able to respond to threads simple threads on the forum and I hope to download the documentation progress thus far and start contributing, but I wonāt be able to really dive into the docs until I get back on June 6th. So Iāll be working on the docs some but donāt expect a PR from me just yet.
Some comments from the flurry of activity that took place the past few days:
Writing a guide like this is challenging. I agree with Kai, certain things need to be be find able. The challenge I think is that we need to support the complete newcomer, the novice OH user, as well as the experts. Its not easy. The structure I suggested was an attempt to address all three of these users and while Iām gone Iāll see if I can move stuff around into this structure and see if it helps address some of these issues.
I completely agree with @kai. Instructions about tweaking the start scripts and modifying the default port should be in the troubleshooting section under a title that refers to the BindException one will see when/if they need to do this. The vast majority of users should never have to deal with this problem.
I completely agree but I think the commands need more context. Lets say Iām completely new to OH, new to Linux/Unix like operating systems, and new to Karaf. If that is where Iām coming from, I would need a lot more context for when and why I would ever want to run these commands.
Side note: Given it has been a topic, I notice on the website that even when starting a sentence, openHAB is spelled with the lower case āoā. So should we just completely standardize on openHAB always starting with a lowercase āoā? To me it looks just as awkward to see it with a capital āOā as it does to see a sentence start with a lower case letter. If we create one simple rule for this it makes it easy to follow and enforce.
I have a feeling that the structure of the documentation will change over time as more of it gets populated and we get a better feel for how it works. For now it would make it much simpler to merge them into the same document structure. Itās HTTP so it isnāt as if we have to page through each screen to jump to a section of interest.
Which is an excellent approach for a start. However, the Getting Started guide needs to primarily focus on the average user. Unfortunately if you had to modify the scripts and change your ports you were not one of the average users. Having to change the default port is not something the only a tiny fraction of users will ever have to do. I agree with @kai that a better approach would be to provide a link to the Trouble Shooting section at the end of the installation instructions and document changing the default port instructions there as I discussed above. Changing the port should be something that is done only as a last resort to solve a problem, not something we want to encourage.
Absolutely! And donāt take any criticism or suggestions from @kai, myself, or others personally. You have stepped up and actually produced something which is more than Iāve been able to do thus far. It is hugely appreciated!
Once you have something to actually look at it is really easy to see what you donāt like about it. But please please please donāt think that we donāt appreciate what you have done.
Working together I think we can generate excellent documentation for OH 2.
Iād like to close with a comment on our different perspectives which I think it directing a lot of the comments that @kai and I are making.
@kai - developer of openHAB, head honcho, and THE openHAB guy. He has the history, the background, the code, and the architecture all in his head and the passion and leadership to drive the openHAB project forward. He has the vision of where openHAB is and where it is going.
@rlkoshak - frequent commenter on the forum focusing primarily on helping new users with problems and helping users work with the Rules DSL. Consequently I have a good feeling for what problems newcomers experience and what documented concepts could ease the transition of newcomers to novice users of openHAB. Iāve also a corpus of detailed answers to many of these questions and an approach to explanation which seems to be appreciated by novices and experts alike (at least so Iāve been told).
@bipphilippe - newcomer to openHAB and therefore has a very fresh knowledge and experience what a newcomer has to go through to get openHAB up and running
@MARZIMA -I think it is safe to call him a novice openHAB user and therefore is close enough to being a newcomer to remember what he went through to get it up and running but also knows enough to know what he might want to know in order to progress.
I firmly believe that all of these perspectives are going to be very important to the documentation. And because of our differing perspectives we will disagree on certain things like structure and content. And that is fine and to be expected. But we should be able to work through these disagreements and I believe the documentation will be all the better for it.
Rich
1 Like
Hi @rlkoshak thanks for your input.
But I need to corret it a little bit, since I know openHAB since around 2011/2012. Not 100% sure the year, but I remember I was thinking about creating a bundle for Hue back than (I had Hue and Kai made a talk in Ludwigsburg/Germany about OH) since I was deep in OSGi dev at that time. Iam a long time user of it since years, but I was never much active in the forums. Just changed that to full active 
I cant count how many versions I installed on Synology or Raspeberry Pi, but I always tend to reinstall stuffs (even with the IDE). I like keep staying in touch with the enhancements with OH and Iam more an old fox in a newcomer pelt 
I think your point is very good. We are all different heads, but we all should find a good way to make this docu greater. I think we should understand what @Kai gives as Feedback (not only because he is being THE man 
), rather than his valueable experience in what worked out as good docu and what not.
I am sure we can manage that and if one says its to complex or not good, we should think about how to improve it. Let s get the best out of itā¦
@bipphilippe great what you did. Also thanks for your ideas. I will take a look into it. Add my stuff where feasable.
@Kai stupid me(hmet), but I cant find the latest changes of phillipe in github. Did the PR went trough? I think I missed that. In my local jekyll setup I couldnt find big changesā¦ just wanted to read it one time to check the state.
Thanks & BR
Mehmet
After searching around for other examples, the most common answer is that openHAB should always be spelled openHAB, regardless of where it appears in a sentence, but effort should be made to avoid starting sentences with it. By comparison:
Some say iTunes is a great program. iTunes is not a good program, others say. ITunes, on the other hand, is neither, because itās misspelled.
1 Like
I feel stupid for this question :
I have integrated your PR and it appeared in the list of commits.
What should I do now ?
As openHAB is a product name, I think this is the only correct way to spell it. Think of openSUSE, you shouldnāt write OpenSUSE either (though I think Iāve seen it more than one time misspelled).
1 Like
Been using openHAB 1 sinceā¦ 1937? (I donāt remember) I am new to openHAB 2.0. Can we add a note about the difference between offline and online version? It took me some searching to find a blog post from Kai that explains the difference is how add-ons are loaded. At least, this should be on the downloads page. Thanks to all who contribute to the documentation and write the code. Long live openHAB!
Just a heads-up: I worked yesterday a few hours on the documentation and re-sorted it a bit to also accommodate @rlkoshak input on the TOC, so that heāll be able to easily add his wisdom to it.
Iāll merge this changes latest on Monday, so we all can then continue to fill in content 
Ok, here we go: http://docs.openhab.org/index.html
For getting started, I have gathered the different tutorials under its own top menu entry: http://docs.openhab.org/tutorials/
The āmainā documentation is the āuser manualā: http://docs.openhab.org/overview.html
This is a bit to what we had as the āreference guideā before. When working through the stuff, I simply noticed that the user manual cannot be a step-by-step guide. There are e.g. far too many installation options available (see the menu on the left of http://docs.openhab.org/installation/index.html). Realistically, we can only pick a few examples and guide newbies through it in a tutorial.
This āuser manualā should be a good place to add information as it comes, I have tried to already create placeholders for @rlkoshak contributions that will now start pouring in, right?
One further nice automation that I introduced is the list of 1.x add-ons - this is now automatically constructed from the feature.xml of the openhab repo.
Also note that I have created a PR for ESH for documentation that should imho be put in there (everything that explains core concepts as this is not specific to openHAB).
I hope you are all ok to move forward with this structure, especially @bipphilippe. If so, it would be awesome if you all could help filling it with content
Ah, one thing I forgot: I also created a README with details on how to contribute to the documentation.
One piece of information that is still missing and that I would like to briefly discuss: How to deal with diagrams? In ESH, we have agreed to use http://draw.io and check in the source files with the images, so that future contributors have a chance to modify and update existing diagrams. Shall we apply the same arrangement here?
I will start editing this evening. Is it better to make a whole bunch of edits and one PR at this stage or make smaller logical edits (maybe a chapter) with a PR for each.
Iām inclined to say the latter but could see lots of PRs being its own problem.
I have no problem with draw.io. I think it is very important to have the source available so the drawings can be kept up to date with the software. Iāve not used it before but have no doubt it will work great.
I promise to merge them asap, so this should be no issue.
Btw, I just added another short new tutorial, which is about the demo setup: http://docs.openhab.org/tutorials/demo.html
I needed this, because the ESH documentation refers to it.
It is similar to the āoldā setup instructions, which can then be reworked.
Looking forward to your PRs!
What editor do you advice to edit README.md on Windows ?
I mean an editor that will render the text like in Within.
Did you try Markdownpad2, thatās what I used before editing those files in my IDE.
I noticed that the sorting of the bindings table isnāt working. Iām not familiar with Jekyll / Liquid, but it appears the only way to fix this is to either add a plug-in or add extra code to do case conversion.
Is there a preferred method (are plugins possible with how this is all being built and deployed)?
Today I created some first input for a logging chapter. The text is written for the more advanced user, so I assume best place for it is the user manual. However I struggled to find a good place in the current structure.
My first idea was to add it under āFeaturesā. But that then I realised that a new chapter containing adminstration related topics might be a better place for logging.
What do you think about adding a new chapter to the user manual with topics like:
Administration
- Logging
- Karaf Console
- User Management
- Security
Details are in this PR . Please note that this is my first PR, so please bear with me in case something is wrong.
Joerg