HowTo make changes / minor corrections to the documentation?

At the end of a doc page there is a link to GitHub whichs leads me to the original file for the doc. I understand, that i need a GitHub user to be able to login. After logging in, i get a page like shown below:


image

Having quite no knowledge about how to use GitHub, reading about “fork”, “issues” and “pull requests” i have a simple question:
Do i have to edit the file, give a short and a long reason for the change ab press “Propose changes” and that’s it? So someone else with write access will have a look an possibly commits the change?

EDIT: do i have to take care of the forked file?

Thanks for advice!

Short answer: Yes thats a possible workflow.

Long answer:

Fork:
Is basically a copy of the openhab-docs repository where you can make your changes.
This is where your edit will be saved (at least temporary)

Pull Request:
This is the next step.
You edit the file (remember it is stored in your “fork”) and then you request a pull to the original files.

There a maintainer (in fact that will mostly be me for the docs) can check your changes and suggest improvements and additions.
At some point the Pull request will be accepted and get merged into the main docs.

One thing ahead:
When you will open your pull request you may see a red x saying your dco check has failed.
Don’T worry about that too mich. We can solve it and it is no veto against your pull request.

I have written down what happens (and how to solve it before) here.


But thats not mandatory to understand for a first pull request. :slight_smile:

1 Like

Hi Jerome,

i think a lot of people will appreciate a more detailed explanation how to use git to propose changes to the documentation. Maybe a real world example will help.

Hey Thomas,

That’s on my long-term to do list already.
Maybe i should switch it to “short-term”.

Maybe i should just start a wiki post with some basic explanation this week.
From what i have seen in the documentation area for the getting started tutorial wiki is a good base to work on.

1 Like

I would lovw to help and check every step with may system, because i have not a real clue about forking etc.

There is a start to some of that at How to file an Issue. I can make it a Wiki or feel free to copy as much or as little as is useful. It mostly focuses on creating an issue and a small PR through the web page (like OP’s original work flow).

1 Like

I think a good start is that the user uses visual studio code fpr editing his item files etc.

Then hee needs to create a git account and install git and an appropriate addon in VSC, bute then …

If one uses vscode for openHAB already this would fit perfectly.
But for someone who doesn’t use vscode yet it would be another step to fullfill.

In my view we should explain plain website based editing and let the user “jump” downwards if vscode is already present or wished as editor.

When I try to help people I usually make a distinction between small and easy changes and big changes. I direct them to the tutorial I linked to for small easy edits. For bigger stuff I always say “open an issue first” and then go from there.

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 :slight_smile: .
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. :slight_smile:

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:

  1. I would quite like to help improve the documentation.
  2. 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. :stuck_out_tongue:

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.