Contributing to the documentation

Tutorials & Examples
1

This was part of another thread where @Dim was so kind as to help us with step by step instructions on how to help with documenting OpenHAB. I was afraid I wouldn’t be able to find the thread again and sure enough it took a few minutes.
here is a link the the thread
https://community.openhab.org/t/unsure-about-installation-procedures-for-windows/46232/2?u=andrew_rowe

Check:

  1. Documenting openHAB 2
  2. Documenting openHAB 2

Ask in that thread anything you need on how to modify/edit/etc any part of https://www.openhab.org/docs/

Quick & Dirty:
0) Create a github account (if you don’t have one)

  1. Open an Issue on the proper github section describing the problem
  2. Edit the relevant page (it will create a fork in your github)
  3. Create a Pull Request to submit your improvement and mention that it closes the issue that you created on step 1 above

If it’s main website content:

  1. https://github.com/openhab/website/issues
  2. https://github.com/openhab/website/blob/master/.vuepress/components/InstallInstructions.vue

If it’s generic content:

  1. https://github.com/openhab/openhab-docs/issues
  2. https://github.com/openhab/openhab-docs/blob/master/installation/windows.md

If it’s binding specific docs entry:
1a) https://github.com/openhab/openhab1-addons/issues
1b) https://github.com/openhab/openhab2-addons/issues

4 Likes
2

If there are additional questions, which have not been answered i would love to help out here and help improving the startpost. :slight_smile:

One thing i have already in mind is this one:

DeepinBildschirmfoto_Bereich%20ausw%C3%A4hlen_20181109191057

The docs are providing edit this page on github links in nearly every area of the docs.
This way you can easily find out where the file you want/need to change is maintained.

3 Likes
3

Wanted to add a link to the contributing guidelines:

4

My experience with github has up until now been confined to contributing original works, I have never made a pull request. Reading the contribution guidelines I linked to above, I have a few questions.

I forked a document and made a few small changes which involved re-wording the first paragraph to make more sense simply to test the process. When I was done, I clicked make pull request button. The page I was taken to stated something to the effect that I could merge my changes myself. If I make a bigger change, I might want it to be reviewed by my peers before merging but wonder if anyone will bother reviewing the changes and merging. Should I just merge my changes myself? Now that I’ve made the pull request, I no longer see anywhere to merge and the original hasn’t been updated but shows now pending pull requests

Quoted from document:
Commit messages must start with a capitalized and short summary (max. 50 chars) written in the imperative
/quote
What is the ‘commit message’ and what is ‘the imperative’?

And also signing off your work section. Is all that is necessary for licensing is to add the line at the bottom but with my name and email address?

Signed-off-by: Joe Smith <joe.smith@email.com> (github: github_handle)

I realize this is not necessary for small one or two line changes but if I spend a lot of time changing a document, I want to make sure it can be used

5

and

6

Thank you @RolfV excellent explanation, good read (funny as well)

7

That’s nearly correct.
The sign off is done fully right, if you add it to every commit you make.

We don’t take it that serious in the docs repo compared to other ones so a sign off in the pull request description is fine too mostly, but of course it would be nice to keep it right for every commit you make.

Signing of can be really easy when you use an editor like vscode and have got installed on your machine.
I always wanted to write up a little tutorial for this.
Seems I should start with it in the nearer future.