openHAB 2.2 stable release

[ThomDietrich]

Hey guys!
Kai proposed to release a new stable version of openHAB on the 18th of December (not officially announced yet, please hold back the information till he announces it publicly).

The release will cause a spike in visitors of the documentation page by both existing and new users. I believe a good consistent documentation is an important aspect at this point. That is why I'd like to push the documentation efforts till this date.

@bgilmer77 @Confectrician which aspects where you planning on working on next?

I personally want to work on the add-ons READMEs. Many of them are malformed (broken Markdown syntax) or inconsistent and do not offer a good first paragraph (see http://docs.openhab.org/addons/bindings.html -> Netatmo). This is a big task and I'd love to share the work.

Please add your comments below with aspects of the documentation you'd like to address before the upcoming stable release.

Best! Thomas

[Confectrician]

Broken Markdown Syntax is a good starting point in my view.
18th of december isn't that far away and i think we won't get bigger topics done until that point.
Time before christmas is always busy and limited.

Should we split up the work with the add-on readme's?

[ThomDietrich]

We could still complete some articles for example. It would be good of all of us went through the docs page by page and noted down what comes to mind.

Before working on the add-ons I'd like to adjust one remark setting. I'm not sure about the restrictions it imposes on lists. http://www.cirosantilli.com/markdown-style-guide/#empty-lines-inside-lists - not sure about the best settings here.

Also: We should check if there is a remark setting for http://www.cirosantilli.com/markdown-style-guide/#punctuation-at-the-end-of-list-items

Is there anything else you encountered during the last weeks you'd like to cover in remark? One thing that is sadly not possible is the restriction to one sentence per line. That is still something we'd need to do manually. _ have a Pull Request ready over here but I didn't find the time to finish it -.- retextjs/retext-sentence-spacing#6

Regarding the split-up: There are a few repositories we have to work on (ESH, OH1, OH2, ...) We could split up by repo plus an alphabet range. You may call dibs on whatever you like NOW.

In order to keep the changes clear I'd suggest to do an only-remark-markdown-correction first, then work on the actual content in separate PRs.

I'm calling dibs on the ESH repo for the complete remark sweep.

[Confectrician]

In order to keep the changes clear I'd suggest to do an only-remark-markdown-correction first, then work on the actual content in separate PRs.

Totally +1. Markdown only PRs and no discussion, if someone asks for content changes.

We could still complete some articles for example. It would be good of all of us went through the docs page by page and noted down what comes to mind.

I will take a look through the issues. I have the nested sitemap elements in mind but nothing more at the moment.

[bgilmer77]

@ThomDietrich @Confectrician I took a quick pass through the documentation. Here are the only major things I found.

In two places, the Windows 10 APP and the Advanced Functionality, we have Contributions Wanted. But in both cases, there are short pages with links that direct people to other resources. It seems to me that we might want to pull down the contribs wanted request on these two pages. WDYT?

Also, when you say look for MDs, I assume you mean linter errors. Also, just to be clear, all of the add-ons are in the ESH repo - correct? So basically the task is to pick off an add-on, load it up, fix any linter errors, and then create a PR - all in the ESH area. Correct?

[Confectrician]

I think it would be ok to do several addon readmes with one PR.
Maybe not 50 in a row. 😄
But 5 or 6 readmes in one PR should be fine.
This way only one PR has to be reviewed and we didnt want to add content changes anyway.

[ThomDietrich]

Hey guys,
it would be great if you were able to provide some last things. Otherwise it's also fine. I've been working on openHABian all week and will net get around to do much in documentation now.

[bgilmer77]

@ThomDietrich I will be able to contribute this week. I was going to work on correcting linter errors, starting in the bindings. I thought it would be good to do one PR for a group of bindings all with names starting with the same letter. For example, all bindings starting with 'A' in the name would be in one PR. I was going to do linter errors only - nothing else. I propose to name the PR "[add-ons starting with "A"] Correct linter errors", and so on. WDYT?

[ThomDietrich]

Yes sounds all good. You don't have to be too systematic. The important thing is, that you use the linter settings from the docs repository and that you pay attention to what I said about loose lists above...

[bgilmer77]

@ThomDietrich Okay - I will work on this later today starting on the bindings. Question - I already found that the /bindings/autelis/README.MD has a linter error, "Cel should be padded". I can mess around with it to figure out what the complaint is, but I wonder if you know right off the top of your head. I gather that this line, which is part of a table, does not line up with the header. Is that correct?

[Confectrician]

I will try to add some things too until 18th, but i am really busy @ work last days before christmas (as usual).
I can promise nothing at the moment.

[ThomDietrich]

A few more notes wrt the linting rules.
First you'll find documentation for all remark packages here: https://github.com/remarkjs/remark-lint/tree/master/packages
"Cell should be padded" means that there should be spaces between content and table frame. Tables are easiest reformatted by running them through http://markdowntable.com/
For general Markdown recommendations, please see: http://www.cirosantilli.com/markdown-style-guide/

Have fun!

[bgilmer77]

Okay - I am ready to start on this. First stop will be Bindings.