HowTo make changes / minor corrections to the documentation?


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/ at master · openhab/org.openhab.binding.zwave · GitHub
Thing docs: org.openhab.binding.zwave/doc at master · 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 :slight_smile: ) 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 :slight_smile:

1 Like

Earlier in this thread I posted a link to the Database guide that tells people how they can contribute.

1 Like

@Confectrician Here is an example that needs to be on the website, not just in GitHub.

Hey @Bruce_Osborne

Yes, we talked about that topic here: HowTo make changes / minor corrections to the documentation? - #19 by Confectrician

It should be available already:

1 Like

OK I just wanted to be sure that one was included.

If you want to discuss each and every documentation issue, feel free to do so. But someone who is capacle should adjust the title accordingly. Or i can do for you. Just let me know the title.

Sorry @yab looking back it was maybe not the best discussion to takeover your topic.
I can open an dedicated one, if the notifications get a bit overwhelming.

I have created Discussion for "How to contribute to the openHAB Documentation"

And additionally my intention was not to discuss each needed Documentation topic here.
I wanted to discuss the contribution wiki and its contents.

1 Like

Not a problem for me, maybe you got me wrong. But reading the title i’d not expect the discussion we have now. Easiest solution seems to be (for me) changing the title.

1 Like

Maybe we should keep this one for some general suggestions and use the other one to really discuss the wiki article, so feel free to change the article.

But generally i would say that we should add github issues at some point of suggestion.

We’ll see what (if) happens here now. If it stays alive, i’ll possibly change the title to …

1 Like

I just read the article and found most of my questions answered below “I Can Fix It Myself!”
I didn’t give it a glance before, because i was not searching “issue” related info from my point of view.

Thanks for this feedback.
I will then read carefully over this too (i have linked the thread above anyways already in the wiki) and see how we can in corporate the contents within the wiki article too. :+1: