Discussion for "How to contribute to the openHAB Documentation"

Please use this topic to discuss the the

wiki article and its content.

Please use github to add wishes and suggestions for specific articles.
This topic is meant for improving and extending the wiki explanations.

2 Likes

I wanted to adjust a typo. So this may have been something you call “small change”. But “HowTo contribute a small change?” has not been a question itself for me while thinking about howto make my first change.

presets when i started:

  • GitHub user present
  • never used GitHub before, only similar tools a while ago. So i have an idea, what issue, pull request, fork, branch etc. is, but don’t know exactly.
  • no knowledge about type of use and processes of the openHAB community

While reading the doc in question, i realized a typo. And i realized before, that there is a link to GitHub at the end of every doc page. So i selected “Edit this page on GitHub”. After logging into GoitHub as requested the original file (well: copy of as i learnedlater) of the doc was shown to me and i was able to edit it.

At the end of the form on GitHub i found this:
image
So fill in a short and a long description and fire off the proposal.

My questions before pressing the button so:

  • is the given text for the short decription is ok/enough?
  • long description seemed clear to me: cleanup typo
  • what happens when i select “Propose changes”? Sure: my change will be presented to someone who will decide to accept it for the offical docs or not. Quite obvious.
  • after pressing the button i was told, that a local fork had been created and i got an error message (which i was told before by Jerome).
    a) do i have to take care of the fork? Maybe just delete it? When?
    b) DCO error. Oh yes - i had been told of that one. But what does it mean? google “github dco” was my friend.

What i want to make a point on is: the question “big or small” change to the doc never arose. It was more like: “What do i have to do after having selected “Edit this page on GitHub” in one of the docs?”. And “What is the following process and what do i have to take care about?”.

All this is not a big deal. It’s a usecase when someone thinks “i should correct this in the doc” while while reading it.

From other viewpoints looking at small and big changes totally makes sense.

EDIT: did some cleanup of my terrible artile. Sorry to previous readers.

Totally right and we will never cover the situation that someone just uses the edit link.
We have to guide manually then, which is totally fine for us.
We decided to add these links, to encourage user in contributing.

In fact i would call about 98% of changes done via “edit this file on github” small changes and thats what i am aiming for the contents of that wiki part.
I would like to have this par as explanation for everyone reading here first, but also as something to copy it over via link to a user who has already started a pull request and has questions aside.

Somethign like a “Thank’s we will get this merged and here is some background for your questions.”

Also quoting @Dibbler42 here to ask him for some proofreading and feedback, since he suggeested it.

1 Like

I just read Rich’s article about filing an issue. My questions are answered there, as stated also here.

1 Like

Fantastic tutorial! Thanks for positing it. I’ve nothing to add. It’s great!

1 Like

I have extended the small/large changes part now.
Probably i am able to finish the first post today.
Proofreading already welcome.

1 Like

Thank you for working on that article. Some feedback from me:

I miss a “to” in this sentence in the original version:

Right now while the rest is missing, i don’t understand, what “that” refers to:

Which informations about what? Maybe it becomes clearer when you had the chance to write more, but i’m not shure.

Thanks for the feedback @yab i have added the to this was a typo indeed.

I have also moved the subsections a bit down and rewrote that sentence you quoted so it will become clearer hopefully.

Finished the first post from my side and will now start with the specific posts about small and large changes.

2 Likes

In had a first look at
# What happens when i proposed my contribution?

typo:

shorten/delete emphasized?:

2 Likes

An other typo in What happens when i proposed my contribution?:

1 Like

Thanks for the documentation already! Although not all parts are finished yet, it did help me a lot already.

In respond on your post in the other topic about API tokens:

Since the part of visual studio was not ready yet, used the website of visual studio to read how to install the GitHub extensions and start loading the documentation part.
Perhaps it helps for inspiration: Working with GitHub in Visual Studio Code

1 Like

Thanks for the input. :slight_smile:

About the vscode docs you have linked:
I would call this already “advanced”.
It provides some nice funtionality on top, but it has most benefits when you have understand the fundamentals of git already.

I would explain a simple approach for the vscode part.
VSCode brings git support in standard without any extension needed and that should fit for the average contributions in first step.

Typo fixed. Thanks :+1: