Just that you believe me that this is on the long term list^^
I just had a look at that and feel it to be a bit overwelming for documentation changes. Looking at a doc page and realizing a typo f.e., i just have to use the link to GitHub at the end of every doc page, (after logging in) may change the doc file and propose the change.
Because i never did this before, I wondered about the “fork” and if i’d have to care about that fork having been created. And i don’t know what will happen after pressing “propose change”. @Confectrician: yes, i am interessted in 
.
So for the correction of the documentation, i didn’t need to know more. I did not have to create an issue etc.
What i feel atm is, that there should be a very simple explanation of the doc changing process and an other (like the one from Rich) to file issues and follow them up to a solution. Maybe i am wrong, though!
1 Like
I have started with
and suggested to continue discussion here.
I am trying to add some graphics aside, so it won’t take a whil until i am finished with everything.
Feedback already welcome.
1 Like
i strongly suggest ALL official documentation appear on the website. Many times for openHABian, for example, users are expected to read the README.md file on gitHub. the Docker Hub docs should also be replicated in the website.
The preceding is only my personal opinion and an attempt to help newcomers.
Yeah to be honest, this is on my todo list for a too long time.
So in short. Yes that’s the way it should be.
1 Like
This is tangentially related, and I’ve never seen it mentioned before so maybe I’m just the strange one:
- I would quite like to help improve the documentation.
- I do not want to print my full name and email address on the internet.
Unfortunately, due to the sign off requirements, I can only contribute one liners or minor corrections.
If the sign off rule exists because of the way that openHAB is licensed then so be it, but if it’s a hang-over because the code has to be signed, but not strictly the docs, then perhaps this requirement could be reviewed?
I don’t intend to argue about it at all - I perfectly respect the decision and rules: just putting it out there why I currently cannot contribute to documentation.
The docs are licensed and maintained under the same Organisation as the code is.
And the Organisation decided to require a sign-off at some point.
I would say that the docs repo handles already most of the sign of statement exceptions within the Organisation.
But with my current information level i am not able to omit the sign-off statement completely for large edits.
Maybe you could finde someone who is willing to transfer improvements from here to github, but that’s of course some effort that would have to be made on top.
Indeed - I wouldn’t want to burden anyone with that at all!
As I say, I’ve never seen anyone else mention this as a barrier to entry so if you lift the restrictions you might only gain one extra contributor: might not be worth the headache!
For anyone who reads this thread, don’t sweat it, just do it, use the web interface the first time, follow the directions and Jerome will help you!!! He helped me make my first pull request and I screwed it up and he was super patient with me and taught me how to do it
Yeah Andrew about that… You owe me some coffee. 
Just kidding.
We are all here in our free time and to get some progress.
Thats the common goal and thats how we should treat each other.
@Bruce_Osborne
You got me a bit with that openhabian thing so i checked it and the effort needed wasn’t that much.
@hafniumzinc
I am handling the sign-off very loose also, when there are 5 or 6 oneliner changes.
So there is stil somepthing possible.
I would not accept that if there was a complete article rewrite.
2 Likes
It is interesting you list Z-Wave as a separate source. I thought all developers were required to provide documentation.
For Z-Wave, the Thing documentation is actually automatically generated from the community maintained device database that currently resides here.
The database guide for contributions is here.
See:
The thing documentation for ZWave is a special script indeed.
But the solution is pretty simple.
You are able to add docs with the site posted above but finally they will end up in the ZWave binding repository, whre we will fetch all docs pages.
Binding docs: org.openhab.binding.zwave/README.md at main · openhab/org.openhab.binding.zwave · GitHub
Thing docs: org.openhab.binding.zwave/doc at main · openhab/org.openhab.binding.zwave · GitHub
For Things the documentation must be in the database where a script builds the text for export to gitHub. Otherwise any changes there will eventually be overwritten. I help write that script for the new database site. @chris can verify this,
Correct - any documentation related to things must be made in the database entry for that thing to avoid it being overwritten when a database export is performed. General docs (ie in the README) can be made directly as a PR in GitHub.
Each device has a field in the database for usability information (I forget the exact name) - this is where we can add anything that user might want to document about a device.
1 Like
Please dont tread things in my posts that have not been written there.
I explained how the documents end up in the website and never gave any advice at some point to edit in a different way than done now.
Sorry - I had not read he whole post and was just answering a question that someone specifically asked me!!
That said, you raised the question of ZWave only 2 posts ago, so I actually don’t see what is wrong with this clarification since clearly things are different your ZWave than other bindings.
I was trying to add the actual source for the thing data because I assumed you were not aware and I wanted to assist with accuracy for the end user. I my opinion a user would get confused and frustrated if they made he change in GitHub and then found it later reverted.
Sorry for my attempt at helping. Feel free to ignore.
Sorry @chris i wanted to reply to bruce.
I just wanted to clarify that it was not my intention to give advices on how to document zwave docs.
@Bruce_Osborne yes you are right after reading again i noticed that this should be added to a tutorial on how to contribute to the docs.
Is this described somewhere in the repository already?
1 Like
No problem
There is a section in the README about the ZWave database - it probably doesn’t specifically mention documentation so could possible (as always ) do with improvement. Likewise at the bottom of each thing doc page there is a “found an error, or think of some improvements” type link to the database for the specific thing, so it’s reasonably well documented (I think) - or at least we’ve tried to make a reasonable attempt to document it but I’m open to improvements
1 Like
Earlier in this thread I posted a link to the Database guide that tells people how they can contribute.
1 Like