I see a lot of folks mention that the documentation needs work. I enjoy writing and English is my native language. I’m a technically savvy guy and do some writing in my line of work. I’m a bit of a new comer to openHAB, but my personal installation is running and I’ve found my way around the system well enough to suit my needs. I believe I could bring a new comers perspective to writing documentation. I like openHAB and I believe in open source software (and hardware) and I want to help. If any of the developers needs assistance with writing the documentation for thier binding or whatever, please feel free to post here or message me. Also if a user finds a part of the documentation that is lacking clarity or contains mistakes but does not have the time to fix it, please feel free to post in this thread.
@Andrew_Rowe The docs are handled through github. You may want to consider checking out the already known to-do list on github:
Just check out the 98 issues (both from a user and a developer perspective) listed, maybe you will find something that you want to tackle.
So true. Openhab is a hidden gem I just discovered and put to work. I love it. Great work. But the documentation is suboptimal.
If you could describe how to connect to myopenhab.org this would be great:
Update java 8 to requested version (this was breaking at first my unifi controller)
Install cryptography extension
Then gpstracker would be great
Are these instructions and links insufficient?
In my opinion these instructions and links are not sufficient for java amateurs. But that is a matter of proficiency.
There is choice, but this creates confusion.
Which version to choose for installation on raspberry pi? A link to this page would be useful:
https://www.azul.com/downloads/zulu-embedded/ (with a recommendation which version to choose. 32 bit, Hard Float, 8u192 worked for me.)
- Also this misses the necessity to install the cryptography extension. But not sure whether this is really necessary.
- Unpack in /usr/lib/jvm
- sudo update-alternatives --install /usr/bin/java java /usr/lib/jvm/zulu8.33.0.134-jdk1.8.0_192-linux_aarch32hf/bin/java 150
- sudo update-alternatives --config java
Those are just suggestions.
I’d like to make a proposition to you as native speaker and newcomer:
First, please browse the docs from the very beginning and make PRs (pull requests via the link at the bottom) to change them into ‘good’ English wherever you feel they are not. Don’t be afraid of introducing false statements content-wise, all PRs will be verified by the docs maintainers and discussed with you if required.
Second, please also have a special eye on information that you felt to be missing, misleading, contradicting or in the wrong place when you tried to get your own system to work. This is hypertext so you can easily branch and forward-reference to the pages where you finally found the information (to not repeat information is a fundamental principle of OH docs).
Thanks for your offer.
Hi Andrew,
Your offer is very much appreciated. We are always looking for people who are eager to help. If you have any questions you might want to get in touch with @Confectrician as he is one of the maintainers for the documentation repository.
Thanks for mentioning me @cweitkamp, i have subscribed to this thread, to keep in touch with the topic. 
Great suggestion, I have a github account, I’ll get to work!
Thank you @mstormi
Reading another thread which mentioned the documentation for new users reminded me of when I first started using openHAB and is one of the reasons I started this thread. I think this is what you mean by
‘from the very beginning’
In other words, paying close attention to the introductory section and concept sections at the beginning of the documentation. As I feel this is the first thing a new user reads and apparently some users decide if openHAB is the right software for them based on those sections, it is important that they are of the highest quality.
Yes that’s what I meant.
And they should be non-misunderstandable to someone who doesn’t already know the system.
non-misunderstandable… that is a pretty tall order 
challenge excepted 
Something to note. There is a discrepancy between the eclipse smarthome and openHAB documentation. On some topics the SmartHome documentation is more extensive and probably could be integrated into the openHAB documentation.
My rational for starting this thread was another thread (which I am not linking to because it kind of turned into a blood bath and needs to die a natural death) but it caused me to remember my first experiences with the documentation. Then I went to look at the introductory portions of the documentation and saw many short comings.
Some of the things discussed in that thread however I feel brought up subjects which need discussed further such as the basic architecture of the program which is presented to the new user. @David_Graeff made a comment about “openHAB also suffers from trying to be backwards compatible” and “There are multiple ways of doing something” Where is a good place to start such discussions and under what topic category?
I noticed that as well but have no idea how such thing should be undertaken, maybe a link added to the bottom of the openHAB page pointing to the eclipse smarthome page
Maybe https://community.openhab.org/c/organisation/code would be a place for this.
We are doing this already for some parts of the esh docs and are in discussion (a bit inactive last days/weeks) on how to improve this also for the development part.
We can grab the whole article during the docs/website build, so technically that’s not a big problem.
Anyway we should think about marking esh docs content during this process, to make clear that there#s another source of information, which one could use if a deeper dive is needed in some case.
agreed
I thought so as well, thank you for the reassurance
Anyway we should think about marking esh docs content during this process, to make clear that there#s another source of information, which one could use if a deeper dive is needed in some case.
With the lastest announcement of moving away from ESH, this will change again…
There is already a migration thread available and of course it doesn’t mkae sense to mark this content any longer. That’s correct.