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