Hi Paul, don’t worry, it looks harder than it actually is. Jekyll took me 5 min to install on my Mac following the Readme. Markup is not more complicated as writing a post here in the forum (and as suggested by @ThomDietrich, just copy&paste the complicated stuff from other documents). The most difficult part for me was (and still is) to commit my changes to GitHub. Are you familiar with GitHub?
The items chapter is still empty, so perhaps this is a good starting point for you?
Hello Joerg,
I agree with all of your assumptions and conclusions. In fact, the conflict between “Features” and “Configuration” already came up in another issue. A related topic was posted here by @rlkoshak. Sorry for not referencing these.
Sounds great. Are you thinking about guiding the user through one practical example (Problematic because everyone has different hardware, ergo will use different bindings) or is your idea more of a general walkthrough (with the danger of being to abstract)?
Agreed, even though, the right place inside of “Installation” will have to be decided by topic. This might get a bit tricky because of platform independent and platform specific topics… To give an example: There is a chapter on samba sharing in the Raspberry Pi article. Should it be copied to the “Linux” article? Should it be moved to the “Linux” article? Should it get it’s own menu entry under Configuration?
There will probably be some changes later but let’s just start in this direction? 
@rlkoshak: you aleady volunteered to create the new structure and find a nice catchy name for Configuration+Features. Might I ask if there are any news?
My idea to address this was that we would have a demo config which included a collection of bindings, mainly non-hardware based bindings, and the tutorial/user manual would reference that demo where examples are needed. This ties both the demo together with manual, provides a means for documenting the demo config, and gives the user a concrete working example to play with as they go through the guide.
In fact, one of my ideas was the user’s guide would walk the user through creating the demo config from scratch so if they followed everything they would have the same thing as the downloaded demo config.
It would be best not to tie the demo to any hardware specific binding though which raises a bit of a problem as I don’t think we can completely ignore the hardware based bindings in the User Guide. That is why we are all here after all.
I vote for yes. At best the Raspberry Pi specific info should be a subsection or chapter in the Linux article. Raspbian IS Linux so everything there should apply. We don’t want to have to document it twice. I question the need to have a separate Pi page in the first place, unless we are truly starting from the point of writing the Image to the SD card forward. In which case as soon as the article gets to the apt-get install stage it should point at the Linux article.
One thing that kai is very adamant about is DRY (Don’t Repeat Yourself) in the docs.
I remember signing up for the catchy name but not the reorg.
I’ll have to read everything that has been written so far and go from there. I wonder if it makes more sense just to get the To Do articles populated before worrying too much about structure. I foresee conflicts galore with people writing an article only to find that page has moved or been combined with another page. But if everyone things we should start on the reorg I’ll do that instead of taking some article off the list that can be written without too much actual OH2 experience (I’ve still not switched over so my practical knowledge is still pretty low).
Given that maybe I’d be better used by doing structural and organizational edits and changes. Thoughts?
As for the section name, my brain is refusing the be creative. I’ve got nothing that isn’t as equally as lame as “Working with openHAB”.
The problem I’m having is that there are really two to three levels of configuration. You have base openHAB configuration which would include things like the reverse proxy tutorial, installation, Designer installation, SAMBA config, logging, and all that type of stuff.
Then you have the configuration of the interface/interaction of openHAB with the outside world (Things, Items, and Bindings).
Then you have the “configuration” which is actually the user’s constructing their custom home automation system (rules, persistence, sitemap). Persistence is kind of in both this and the interface/interaction area so could be put in either place.
NOTE: I notice that there are a lot of capitalized "OpenHAB"s in the documents. I think it was decided in one of these documentation threads that openHAB should have an uncapitalized “o” in all cases, even when starting a sentence. It’s a nit but being consistent is important.
I’m having difficulty finding descriptive names for all three categories that makes sense.
Damn, I should have chosen another example. But okay: You maybe saw, that I rewrote the Raspberry Pi article this weekend. While there are a few RPi specific details in the first third, the rest is completely RPi-unrelated linux stuff. In the sources you can even find comments telling author to move this chapter to Linux. I was going to work on the general linux article next. 48 hours ago I was mainly focused on getting information to text.
Okay my bad. I think it got clear, that there are a few needed structure changes we all agree on. Let’s have them in docs as soon as possible, so contributors have a better feeling of what’s there, what’s missing, what’s the general idea.
@luotaus would you like to create a PR?
@rlkoshak I actually think you of all should work on documentation 
But of course that’s up to you
Yes I can confirm, that only “openHAB”/“openHAB 2” is to be used. I already got scolded by Kai
OK, That is easier for me right now anyway. I’ll pick an incomplete page, create an issue and start pounding the keyboard.
This may give me the kick I need to start moving over to OH 2 anyway. I’ve been dragging my feet while I learn me some ansible, not to mention studying for the CISSP (yuck).
[quote=“luotaus, post:121, topic:10568, full:true”]
The most difficult part for me was (and still is) to commit my changes to GitHub. Are you familiar with GitHub?[/quote] I wasn’t, not really. But i’ve done some reading and think I understand the basic concepts. Fork the original project, add/edit my work, then make a pull request from the original that applies to the work I want pulled over.
I actually found the simplest method for me to work with this was to use Atom on my PC and also install git desktop so I could have a local copy of the openhab/openhab-docs repository. This let me open/copy existing .md files and then work on my items.md file and commit this work to my fork.
I’ve had a crack at this and have a new pull request pending. It may not be perfect, but it’s something at least.
Just created a PR for two chapters of the beginner guide and hope this gives an idea in which way I suggest the tutorial should develop (at least for the moment).
Unless someone thinks this is totally the wrong approach, I would continue with the next chapter.
Hey @luotaus, thanks for your contribution. I really like the detailed instructions with screenshots.
In the meantime I’m working on the Linux installation article and @peaeater wants to work on the references in the OH1.8 wiki. @rlkoshak I can’t directly mention you in GitHub issues, hope you are still receiving the notification.
Hey guys - super fresh at the project, but jumping right into OH2. Would be happy to help in any efforts in between busy work and family life.
Linux sys admin with a “knack” for figuring out and tweaking JAVA (but no developer by any means). Also JS, PHP, Python, and Ruby if I have to jump into the pits of hell that day. Also BASH scripting (obvi)
EDIT: I’m speaking in terms of documentation and testing (thus the post in this thread) I don’t think I have the chops to actually help any dev.
It’s a long story that goes back to when these forums were on the Google site. It looks like you found me though. For everyone else, I’m rkoshak on GitHub.
What happened was a mixup when we first started this forum. All the users were moved over as is (i.e. with their google usernames) and there was confusion about whether we needed to change our names immediately or if we had some time. By the time we all discovered we needed to do it right away or else lose our link to our old postings I had already written a few dozen postings and didn’t want to lose my connection to them. So I kept my name instead of changing it to what I would have (I usually go by paperrhino on forums like these).
With well over 1000 posts now I think I’m pretty well stuck.
I’ll be on a city trip to Prague over the weekend. That’s why I submitted the current version of the Linux/RaspberryPi installation article as PR https://github.com/openhab/openhab-docs/pull/73
Would be great if one-two of you found the time to proof read and comment on it. Thanks!
@pr0f Welcome to the community! Which kind of work would you be interested in? For the article referenced above (mainly this one) it would be great to have an english native speaker proof reading. I’m german, so there might be a few errors in my languaging =)
@ThomDietrich I’d be happy to proof read. I’m not sure I’ll be good for more than testing / proofreading until I get my head wrapped around the architecture of the tool. Heck, I’m still glassy eyed and drooling from trying to read general concepts from OH1 that I need to know to work the product! I’ll check out the link and read over it as I get time.
Glad to be of help.
First of all nice work and respect for all your hard work and effort.
@rlkoshak I’m looking forward for the documentation as you suggested.
I’m not sure but is there already documentation like you suggested in your post, and what this topic is … available to get started with.openHAB2.
At this moment I’m reading this
OH 2 Documentation - as guide line and more information
https://bipphilippe.gitbooks.io/openhab2-compendium/content/ - BOOK
But like already mentioned it is sometimes confusing … too much info.
So I’m really looking forward to the different levels of information for beginner till develloper.
@krismaussen, The official documentation page you should be looking at can be found at http://docs.openhab.org/introduction.html
Hello everyone.
It has been a while since we discussed documentation related details here. That’s mainly because all discussions in this area shifted over to the GitHub Issue Tracker.
The upcoming release of openHAB 2.0 will certainly create a certain attention and openHAB doesn’t have to hide from that. Sadly many new users are scared away by the lack or the quality of the documentation state. This covers both technical documentation, binding READMEs as well as Tutorials and Examples.
With the feature freeze for openHAB 2.0 GA in place, it would be amazing if everyone reading this could consider solving at least one of the following issues! 
All interesting issues: Link
Issues that can’t be solved because of an open question: Link
All issues just asking to write one small text from given information: Link
I want to mention a few users which I remember as being helpful and explaining to others or that have previously offered their help. Yes I did not forget about You!
No special order: @skatun @sihui @robin.muellerbady @jaydee73 @Branden_Smale @Tom_Still @UglyKidJoe @Max_G @erland_lestander @sam_calmes7 @RHINESEL @jlemmer @DocFraggle @elias_gabrielsson @rtvb @Dim @david @kubawolanin
Thank you all for helping others and giving back to this awesome community! 
Has there been any discussion or thought about taking the repo at https://github.com/openhab/openhab1-addons.wiki.git (“the Wiki”) and treating it as the git repo that it is, forking it or just making a gh-pages branch, git mv'ing each page of value into a convention that makes it useful for the overall documentation effort? I see it as a valuable goal to obsolete the wiki altogether for openHAB 2 users, and in the process fold its contents into the whole build process for docs.openhab.org. Just curious on your thoughts about corralling all relevant documentation into the fewest possible places so it can appear happily in the end destination.
In the process, outdated installation and configuration instructions could be corrected, made consistent and streamlined, which is currently a source of frustration for many.
The old wiki would then be left in place with a big “we’ve moved” notice, and instructions for future edits in the new home. Interersted in your thoughts/opinions.
I’d suggest there being a direct link to the documentation from the announcements section of the forum. It is quite difficult to find the link, especially for a new user. It needs to be found easily, and I believe new users probably find the forum before the documentation.
I really haven’t used Github at all. Where do we actually contribute stuff? Say for example, a tutorial (issue #205) .
https://github.com/openhab/openhab-docs/issues/205
Do we write the tutorial in Github somewhere or do we do the tutorial here on the community forum and then make a comment in the Github thread?
I have the same challenge…
I started by installing jekyll on my windows pc (using Chocolatey) and I will proceed with the next steps based on: https://github.com/openhab/openhab-docs/blob/gh-pages/README.md#contributing-to-the-documentation
More news soon
(I think that I have to type up a more detailed “HowTo contribute to the documentation” before I start contributing content to it myself :))
@RHINESEL @Dim let me try to give a short tutorial:
For starters you could look out for smaller tasks where an existing article needs to be edited. All of the qick fix issues linked above (but also many others!) would be such issues (@RHINESEL I’ve removed the Tutorials ticket from that list).
Solving these tasks is very easy! You do not need Jekyll nor any deeper git knowledge. You can simply select one issue, open the related GitHub document, add the needed changes right in the online editor and propose these changes as a “Pull Request”. This process allows others to review every change and suggest further improvements. One special detail: According to this you need to “Signed-off-by”-mark your commits - please do not forget that.
If you want to add a new article (e.g. Tutorial page) it would be the easiest to discuss this in the related issue first. We can help with the needed steps there.
Looking forward to some great contributions Best! Thomas