[Wiki] How to contribute to the openHAB Documentation

Tags: #<Tag:0x00007f4349efe3e8> #<Tag:0x00007f4349efe230>

Contributing to the Documentation can be tricky, especially when you don’t have a software/programming background.
One reason for this may be way of how we are storing and processing the documentation pages.
We do it with a version control system like it is known in software development.

This tutorial/wiki aims to lower down the entry hurdle for interested users, who would like to help us improve/fix the documentation.
We will cover some facts about our documentation and what we are doing with it.

Table of Contents

  • Where does our documentation live and evolve?
    • Repositories
  • How does everything come together into one website?
  • Short overview of our version control
  • What kind of improvement do I want to contribute?
  • What happens when i proposed my contribution?
  • How to contribute small changes via website
  • How to contribute larger changes with Visual Studio Code

Where does our documentation live and evolve?

Our documentation is not located in one place. It is spread over multiple locations.
This may be a bit confusing when you read this the first time, but will make sense if you think about it after the repositories part.

All of our documentation contents are version controlled by a software called git and our repositories are all located at one Hoster (GitHub) who provides this version control.

Repositories

The Documentation articles are stored in different repositories related to their context.
The general docs articles have a dedicated github repository openhab/openhab-docs.

All of the addon related documentations (like those from bindings or actions) are stored and managed in the openhab/openhab-addons repository directly within their corresponding binding/action/… codebase. This way we make sure that binding developers can document their implementation easily while doing the coding. There is another benefit. When bindings get improved/changed, our maintainers can have an eye on a proper doc change to (hopefully) avoid outdated docs.

All docs related to user interfaces can be found in the openhab/openhab-webui repository.
openHABian, the ZigBee Binding and the Z-Wave Binding have their own repositories.

And still there is a high chance that i have forgotten other repositories with docs included.

How does everything come together into one website?

First we are gathering the docs files from all of those widespread repositories into the main docs repository.
This is done in a special way, so you can not see it directly on the GItHub Page until you know where it is.

Build_Gathering

After this, we have to get those contents into our website, which also has a repository on GitHub.
You can find it here: openhab/website
We are know starting a new website build (this can have multiple start triggers) and the chain is getting longer again.

This may seem a bit confusing when one sees it the first time, but we have only the best in mind for you. :slight_smile:
We want to have doc files where they belong logically and don’t want to have one blown up place where no one is able to find the doc file that needs an improvement.
So we are fine with investing some logic and effort to set up this build system and you can do your contributions in areas where they belong to logically.

You want to improve a binding doc?
=> The place to go is where bindings are stored generally

You have found a typo in the openhabian docs?
=> Just look for the openhabian repository and you will find everything that belongs to openhabian

And now the best of all.
You don’t need to worry about the build stuff. We are taking care of that.
I just wanted to show you how it’s done in case you are wondering how all of that comes together.

Short overview of our version control system

Like already written above, we are using git as version control system with GitHub as our hosting plattform.
I will not cover every aspect of git here, but give some explanation for specific terms that you may get in contact with, when contributing. Most of them are even only valid when you are working with GitHub like we do. This is meant as a first point of understanding whats going on during a contribution.

Issues

Github gives the ability to discuss errors or relevant topics beneath the codebase (or the docs files in our case). This is done through so called Issues.
If one faces a problem or has the idea for an enhancment it is highly recommended to open up an issue in the corresponding repository to store and discuss it right where the relevant content is managed.

A guide how to proper file an issue from @rlkoshak can be found here:

Fork(s)

You have learned that our code and the docs are stored in GitHub in a so called repository which is pretty similar to a regular folder structure.
Since it would cause many problems when a big userbase, like ours is, tries to edit files in parallel those repositories have restricted access for only a few persons. (Those are mostly the maintainers of that part of openHAB.)

So it should be pretty logically that you need a place where you are not restricted to save your wanted changes. This is done via Forks.
A Fork is basically a copy of a repository and its contents at the time of copying it.
(The time will get important for the advanced users later.)

When you edit files for the docs you are doing this in your own fork and GitHub is pretty good at this, so that you even sometimes don’t recognize that you are editing in a fork of a special repository.

Pull Request(s)

So you have generated a fork (maybe without knowing it) and changed some docs to improve them.
How do the openHAB Docs Maintainers know, that you want to contribute something?
That’s what Pull Requests are for.

When you have finished your improvements you can propose the changes in opening such a Pull Request and openHAB Maintainers will get a notification on GitHub where they can check what files you want to improve.

We will learn more about this process in the last part of this Posting.

What kind of improvement do I want to contribute?

For the sake of simplicity we will break this down to 2 main paths.
Probably there are different other paths you could choose, but i would leave that to contributors who have understood the main paths described below.

For now we will distinguish between small and large changes.

Small changes are so called oneliners which just correct some typos, a wrong comma, the grammar of one or two sentences.
Oneliners are contrary to their name not limited to one changed line, we just call them this way.
Small changes are also suitable for maintainers to skip the DCO Check (we will learn something about that one too later).

Large changes are anything beyond the scope that was described in small changes.
Probably you will have to adapt and change something during the review of your suggestion.
That’s why we will explain those different.
The effort to start contributing a large change like it is explained below is a bit higher, but it will pay off when it comes to necessary changes during review.

The information on how to contribute are covered in separate posts, which you can find referenced below.
Also the process after proposing a change via pull request is explained in a separate post.

Thanks for your interest so far. :slight_smile:

How to contribute small changes via website

This is explained in a separate post

How to contribute larger changes with Visual Studio Code

This is explained in a separate post

What happens when i proposed my contribution?

This is explained in a separate post

7 Likes

How to contribute small changes via website

How to contribute larger changes with Visual Studio Code

TBD => This will get an extra posting
TODO => Advanced user reference for keeping a fork up to date

What happens when i proposed my contribution?

As you already know now, you would propose your contribution with a pull request to one of the repositories shown above. Lets keep it simple for this example and stay in the main docs repository.

After starting your pull request (we will come to the specific steps needed for this) repository maintainers will get a notification, that a new pull request is available.

Maintainers will then check if the proposed changes are valid in several aspects, which i can only explain for the documentation now. Here i will mostly check:

  • Is the proposed content valid?
    When i am not able to answer this i have to ask back to a maintainer with more knowledge.
    This could be the case for Docker or Synology article changes.
    I am not using those methods and have to get some external knowledge vor validation.
  • Are the changes valid to our docs standards
    Those are mostly things like “Is there one line per sentence”, “are the Headings structured hierarchic”.
  • Is the grammar correct?
    This is where we could need some help in the future since we do not have that many native English speaking proofreaders.

When there are things that have to be adapted or need some discussion, maintainers will add a review.
Here is an example PR with a review:

There was just one blank line too much, which caused me to add a Suggestion. A Suggestion shows up as suggested change in the review and you can adopt this suggestion with 2 or 3 clicks without a need to edit a file again yourself. For small adaptions we use suggestions pretty often.

When everything is reviewed and all discussions are resolved the Pull Request will get approval and we will then merge (that’s another git specific term) it into the main docs.

This will automatically trigger our build server to copy the new contents in our hidden area for the website build and it will then get included in the docs when the complete website build is triggered.
It may take up to one day until you can see your changes.

Placeholder 4

Placeholder 5

This is meant as a starting point.
I will make it a wiki post, when i have finished a first version with my thoughts and ideas.

:slight_smile:

Discussion, feedback, suggestions may be done here: