Rewrite all documentation

[ecdye]

As has been mentioned many times, the openHABian documentation is poorly
written and often comes across in the wrong way. This is an attempt to
start fresh.

The goal is to keep the documentation clear, simple, and easy to follow.
All features should be fully documented and clear. Additionally the
expectations for what is supported should be clear, without making the
wrong impression on the end user, being overly wordy, or harsh.

Basically, make the documentation as great as the rest of openHABian.

[mstormi]

I believe you already recently 'softened' the HW requirements part and this https://github.com/openhab/openhabian/blob/main/docs/openhabian.md#3264-bit-support

What got lost along that way was that users should not be running 64 bit OS or java on machines with 1GB.
Please prominently re-add a warning not to do that.

[ecdye]

@openhab/webui-maintainers Can you help me figure out how to make the sidebar have a dropdown to access a few subdocs like openHABian specific troubleshooting or more detailed feature guides?

[florian-h05]

The sidebar structure is defined in the docs repo:
https://github.com/openhab/openhab-docs/blob/main/.vuepress/docs-sidebar.js

BTW, rather ping the doc maintainers instead of us UI maintainers.

Merry Christmas to you 🎄

[ecdye]

The sidebar structure is defined in the docs repo:

https://github.com/openhab/openhab-docs/blob/main/.vuepress/docs-sidebar.js

Awesome, thanks!

BTW, rather ping the doc maintainers instead of us UI maintainers.

Whoops, I'm sorry, I thought I even double checked, but I guess I wasn't looking close enough.

Merry Christmas to you 🎄

Merry Christmas!

[stefan-hoehn]

Can you help me figure out how to make the sidebar

Did you manage to create it or do you still need help? (I saw openhab/openhab-docs#2434)

[ecdye]

Did you manage to create it or do you still need help? (I saw openhab/openhab-docs#2434)

I think that I got it, I just need to finish making all the changes here first.

[ecdye]

OK @mstormi It is not perfect but it is all that I can convince myself to do for now. It's much better than it was.

[stefan-hoehn]

@ecdye I'll wait for @mstormi 's feedback, wdyt?

[mstormi]

Err do I get it right that you have removed quite many of the original lines 50-150 on debugging?
That's pretty much worsening this document's purpose.

[ecdye]

Somewhat, but it is also partially because much of that content has been shifted around and moved to the main document and this references back to it.
Especially because much of it was a restatement of what was in the main install docs and has been clarified there.

I also removed a little bit of it because some of it was beyond the scope of what we really support anyways.

[mstormi]

but it is also partially because much of that content has been shifted around and moved to the main document

The DEBUG guide was meant to be a standalone document to point people with initial setup problems at, and specifically also those that ignored the official docs in the first place. I agree we should rewrite it but I also think we should stick to that idea.
It was written back when we did not have the hotspot and we did not have network manager.
Both have implications that we should explain a lot better, eventually including what you can do on the comitup console if it does not come up in the first place, or Network manager commands rather than ifconfigs
Plus mention static IPs prominently (that you must not attempt that and what to do to nonetheless obtain the same IP on every DHCP).

[ecdye]

@mstormi I've addressed most of your comments, please let me know if there are any other concerns.