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.
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!
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.
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).
Here is a quick step-by-step I used to get going. I agree it is complicated but I do understand why these steps are necessary. These are taken from some notes I made and I really haven’t kept up. There may be errors or omissions. Note that this is really only necessary for major updates like the creation of a new document or major structural changes. For quick fixes use the online editor as @ThomDietrich described.
You must have a GitHub account.
Once logged in click on your icon in the upper right and select settings.
If you have ssh set up (on windows this would be putty tools installed and pagent running with an ssh key loaded) add your ssh public key under SSH and GPG Keys. If not, generate a “Personal Access Token”. You need one or the other set up to interact with Github from the command line. On Windows you could also get the Github Client program but I have not had good experiences with it.
Add the original repo as the upstream with the command: git remote add upstream email@example.com:openhab/openhab-docs.git NOTE: use the http address if you did not upload an ssh key
Checkout the gh-pages branch with the command: git checkout gh-pages
Merge the changes from the upstream with your fork with the command: git merge upstream/gh-pages
Create a new branch for the one issue you want to work on with the command: git checkout -b <name>
Push the branch to github using the command git push origin docker
Make your changes.
As you go, add and commit changes with the commands git add . and git commit -m "message"
When your changes are ready, go to the github page for your fork and create a PR. Make sure that the openhab/openhab-docs and appropriate branch is on the left and your new branch is selected on the right.
Make sure to reference the Issue in your comment. Closes issue #XXX
Additional commits can be made to the PR by making the changes locally to your branch and pushing the commits.
you can work on more than one issue at a time by working on each one in a separate branch.
Before creating a new branch, make sure to do steps 7 and 8 before creating a new branch to work on
FYI karaf base and home should be the same by most of the time. Karaf home variable is used only when one karaf installation serves multiple processes. Wrapper script points to boot/main class which will not be present in children instances.
Even if its not used in OH better dont change it.
// ok, after checking