openHAB 3 Documentation - ToDo

[Confectrician]

Goal

This issue is meant as a To-Do list for tasks that we have to accomplish for the openHAB 3 release.
This is mainly adressed to the internal parts of this repository and the website appearance.
External content can be fetched from the OH3 branches of the corresponding repositories with some effort.
The contributors of those repositories should check and improve contents themselves in the corresponding repositories.

Accomplished (so far)

Concepts => #1310 (comment)
Installation Guide => #1310 (comment)
Configuration Guide => #1310 (comment)
Interfaces and Ecosystem => #1310 (comment)
Administration Guide => #1310 (comment)
Developer Guide/Appendix => #1310 (comment)

[ghys]

I would say let's create a subdomain like v3.openhab.org, dev.openhab.org or next.openhab.org for the 3.0 docs and deploy a site with its own workflow. The main openhab.org would for now display the 2.5.x docs, maybe with a link to switch to the "next version" site. The home page's "hero" image would be due for a change as well when 3.0 is released, maybe we can also prepare a v3 demo server in the meantime, depending on the burden of maintaining it.

Also, eventually I'd like to revisit the version switcher widget which appears on each page and abandon the principle of staying on the "same" page when switching versions - we overlooked how quickly it can become a PITA when the structure changes (and I suppose it will change significantly for 3.0) and we end up with a lot of dead links. I'd rather put a combobox in the left column with a list of versions and navigate back to the intro page (/docs/) when switching.

[kaikreuzer]

Sounds good to me. Would you create a new site in Netlify? I would then add an dns entry for a sub-domain (next.openhab.org sounds good, although I am fine with any other option as well).

[Confectrician]

I would vote for next.openhab.org too. Sounds catchy.

[bwosborne2]

If you use v3.openhab.org that will be obvious and "future-proof" whenever v4 arrives. You could even just redirect the main page to the latest version.

[ghys]

Updates - There are now parallel processes for 2.5.x and 3.x docs and websites:

	v2.x	v3
General docs branch	2.5.x (default)	master
Final docs branch (w/ addons)	final-2.5.x	final
Current docs preview URL	https://openhab-docs-preview.netlify.com	https://master--openhab-docs-preview.netlify.com
Jenkins jobs (view)	Documentation (2.5.x)	Documentation (3.x)
Gather external docs Jenkins job	gather-external-docs-v2	TODO
Merge docs Jenkins job	merge-docs-v2	TODO
Redeploy website Jenkins job	redeploy-website-v2	TODO
Website branch	v2 (default)	master
Website deploy URL	https://www.openhab.org/	https://next.openhab.org/

(1) @kaikreuzer you might want to configure alias(es) as discussed above and/or enable CF for this one. The black "jumbotron" background is intentional, it's meant to distinguish the v3 website while it's not the production one. The download page has been simplified for v3 for the time being (and the production website only offers v2 install instructions & links).

Notes:

• all relevant changes to the 2.5.x/v2 branches have to be cherry-picked and added to the master branches too. I have changed the base branches and added a reminder to all currently PRs in this repo. Please double-check the base branch when merging PRs.
• we probably won't alter the process for 2.5.x but the process for 3.x is open to changes and improvements since the branches may diverge without breaking the 2.5.x process (everything being duplicated).

[Confectrician]

Thanks for pushing this forward Yannick 👍

[wborn]

I've created some issues for OH3 documentation updates (#1161, #1162, #1163). Is it already a good idea to create PRs to solve these?

[ghys]

@wborn you can but you will only see the changes in the preview site - the Jenkins jobs to prepare the website deployment are not there yet.
Also the website for v3 (https://master--openhab-website.netlify.com/) now runs a more recent version of VuePress, I still have to adapt the preview. It shouldn't matter though.

[bwosborne2]

There should at least be documentation warning that OH 3 is not yet usable. We are seeing quite a few new users blindly trying to run OH3.

[ghys]

@bwosborne2 I noticed, that's why the main website download page https://www.openhab.org/download/ doesn't mention the 3.0.0-SNAPSHOT versions anymore (it used to because of a snafu), and the upcoming new website currently has a warning: https://master--openhab-website.netlify.com/download/
to discourage users from using OH3 in production yet.

[kaikreuzer]

(1) @kaikreuzer you might want to configure alias(es) as discussed above and/or enable CF for this one.

I've created a CNAME entry, but https://next.openhab.org/ now shows a "not found". Any idea, why?

[bwosborne2]

I am getting a WEB PAGE that says "Not Found". That is the default index page on the server. You are probably using name based virtual hosts.

[kaikreuzer]

nslookup gives me different IP addresses:

Name:	next.openhab.org
Address: 104.24.114.50

Name:	master--openhab-website.netlify.com
Address: 167.99.137.12

Maybe I need to give DNS time to propagate? Looks weird as this subdomain didn't exist before...

[bwosborne2]

The default TTL (Time to Live) is 1 hour. Refresh is (2 hours 46 minutes 40 seconds) from DNS server ernest.ns.cloudflare.com

Hmmm.
Name: next.openhab.org
Addresses: 146.112.239.210
146.112.43.224
146.112.43.233
146.112.43.47
146.112.43.13
146.112.43.225
146.112.43.132
146.112.43.183
146.112.43.185
146.112.43.185
146.112.43.47
146.112.43.225
146.112.239.210
146.112.43.233
146.112.43.224
146.112.43.183
146.112.43.132
146.112.43.13

Name: master--openhab-website.netlify.com
Addresses: 2604:a880:400:d0::72a:f001
192.81.212.192

[ghys]

Name: next.openhab.org
Address: 104.24.114.50

Name: master--openhab-website.netlify.com
Address: 167.99.137.12

Seems legit since the first is CloudFlare and the second is Netlify.
I'm not sure about the "Not Found"...

[bwosborne2]

Is there something needed in CloudFlare to point to the new content?

[ghys]

I've created a CNAME entry, but https://next.openhab.org/ now shows a "not found". Any idea, why?

Actually that's probably it, either you do a CNAME or proxy through CloudFlare ;)

[bwosborne2]

It's working for me now.

[Confectrician]

I have worked trough the Pull Requests and we have merged everything except the work in progress tutorial by @rkoshak.
Most to-do's that are left are located in the configuration parts.

I will have a lookup now for the amount of needed changes and will do all small changes in a bulk pull request.
Any help for getting the existing docs to the finish line now is appreciated.
Please give a quick reply here, if you would be able to help on one specific article to spread the needed work.
I would then leave it out from my bulk imporvements.

[BClark09]

Hi @Confectrician,

Added a PR (#1330) with my suggestions for change in the Linux installation docs.

[Confectrician]

Quick merge. :) Thanks for proofreading this article.

[mstormi]

Ouch, that now was pretty interesting to me as well as we've been using those old repo URLs in openHABian until now.
Ben could you please confirm that the stable/release repo will continue to be
repo="deb https://dl.bintray.com/openhab/apt-repo2 stable main"

[bobadair]

I submitted PR #1331 for administration/index.md which has already been merged.
I just proofread concepts/index.md and didn't think it required any edits.
I'm now proofreading installation/index.md.

Is addons/index.md ever linked to, or should it be removed? I don't see that content showing up anywhere in the docs.

[Confectrician]

Is addons/index.md ever linked to, or should it be removed? I don't see that content showing up anywhere in the docs.

I had that question in mind too.
I think @ghys rewrote this for the new addons page we introduced some time ago.
We can remove it later if it really isn't linked anywhere and not useful anymore..

[bobadair]

I've submitted another two PRs after proofreading:
#1335 for installation/index.md
#1336 for developers/index.md

[Confectrician]

I have updated the first posting again.
We have only few tasks left and not all are urgent for the release tomorrow.
I will try to get the Tutorial merged today with its latest progress and add some pages with links to the corresponding Wiki forum threads for the advanced topics.

[Confectrician]

Hi all,

I have (friendly :P) taken over the pull request from @rkoshak #1304.
We have got a working Preview now after some structural changes.
https://deploy-preview-1304--openhab-docs-preview.netlify.app/docs/tutorial/

Could one or two of you do me a favor and proofread it?

Please be aware of missing articles so far.
We won't get everything live for the release,, but i want to have the current version in the website and add some links to the wiki pages until we have full article replacements.

Please use the pull request for any improvement sufggestions or corrections.

Thanks.

[bwosborne2]

I believe there are some steps before creating the Admin user.

Offhand I remember a wizard to set the regional settings as well as an option to add bindings.

[Confectrician]

Please use the pull request for any improvement sufggestions or corrections.

This issue already has many comments and is hard to overview.

[ghys]

I believe there are some steps before creating the Admin user.
Offhand I remember a wizard to set the regional settings as well as an option to add bindings.

No you create the admin user before you get to the wizard (you wouldn't be allowed to make such changes anyways without being authorized).

But I'm realizing some parts of the tutorial were made before the setup wizard was implemented, and screenshots are outdated, there's been changes to many screens since then, so they could use an update.

[bobadair]

Please use the pull request for any improvement suggestions or corrections.

I started proof reading the tutorial files. I assume that pull requests should be made to the rkoshak/openhab-docs repo getting_started branch. I just submitted one there with some minor edits to index.md.

[Confectrician]

Ok i have setup a new ubuntu vm, did a fresh ih3 install and added some (german, sorry) setup wizard screenshots for now.

[Confectrician]

Hey @bobadair,

Do you want to proofread something to the pr (are are you already preparing something)?
If not yet started i would suggest to merge the pr as is and add improvements to the docs repo directly afterwards.

[bobadair]

Great! I see you merged #1304. So I'll submit any further PRs (assuming I have time for some later today) directly to this repo.

[mstormi]

I saw it's live now. There's a wrong line in https://www.openhab.org/docs/configuration/#versatility but I don't know how to change it now.
It's the last line of the blue info tip box: the option is only for items from .items files , but not for Things and .things files.
@Confectrician could you please manually correct that

[Confectrician]

Should be here:
https://github.com/openhab/openhab-docs/blob/main/configuration/index.md

I can take carr but i am working on some wrong things in the beginner tutorial now first.
If you find time earlier you can give it a try.

[mstormi]

#1355

[bobadair]

I finished proofreading the Getting Started tutorial and submitted another couple of PRs with minor edits. But it's important to note that I was only looking at wording, punctuation, etc. I did NOT attempt to verify the technical content. Not that I'm unwilling to help there, but there wasn't time before the release since I'm not yet familiar enough with the OH3 UI to quickly recognize errors.

[Confectrician]

Thanks @bobadair

The way you did it was exactly what we needed here.
If somethings wrong on the content side still, users will tell us very quickly. ;)

NAtive english proofreading is one big gap we have to fill on long term for the documentation.

[bobadair]

Since I'm from the US, my friends from the UK disagree that I'm a native English speaker :-) but I'm always willing to do a bit of proofreading if you point me in the right direction.

[Confectrician]

Hi all,

I think this issue has enough postings now.
With #1346 as follow up in place, we have accomplished all "needed" changes for openHAB 3.
I am still not satisfied with everything, but we can go on with improving things regularly with issues and pull requests now.
No collection issue needed anymore.

Thanks to all of you who have helped out and contributed or gave feedback.
Your help is much appreciated and of course it will be appreciated in the future too.

Have some nice christmas days and a good start in year 2021.

BR
Jerome

[mstormi]

We still a medium to track TODOs, don't we ?
I got word that https://www.openhab.org/docs/installation/security.html#running-openhab-behind-a-reverse-proxy is not up to date with OH3

[Confectrician]

Stated above

but we can go on with improving things regularly with issues and pull requests now

We're in the docs repo, thats what issues are for here.

To your special topic:
https://community.openhab.org/t/nginx-unauthorized-api-request-with-un-pw-prompt-oh3-openhabian/111199/10?u=confectrician