Rewrite all documentation #1936
Conversation
Signed-off-by: Ethan Dye <[email protected]>
|
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. |
Signed-off-by: Ethan Dye <[email protected]>
Signed-off-by: Ethan Dye <[email protected]>
Signed-off-by: Ethan Dye <[email protected]>
Signed-off-by: Ethan Dye <[email protected]>
Signed-off-by: Ethan Dye <[email protected]>
Signed-off-by: Ethan Dye <[email protected]>
Signed-off-by: Ethan Dye <[email protected]>
|
@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? |
Signed-off-by: Ethan Dye <[email protected]>
|
The sidebar structure is defined in the docs repo: BTW, rather ping the doc maintainers instead of us UI maintainers. Merry Christmas to you 🎄 |
Awesome, thanks!
Whoops, I'm sorry, I thought I even double checked, but I guess I wasn't looking close enough.
Merry Christmas! |
Signed-off-by: Ethan Dye <[email protected]>
Signed-off-by: Ethan Dye <[email protected]>
Depends openhab/openhabian#1936 Signed-off-by: Ethan Dye <[email protected]>
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. |
Signed-off-by: Ethan Dye <[email protected]>
Signed-off-by: Ethan Dye <[email protected]>
Signed-off-by: Ethan Dye <[email protected]>
Signed-off-by: Ethan Dye <[email protected]>
Signed-off-by: Ethan Dye <[email protected]>
Signed-off-by: Ethan Dye <[email protected]>
Signed-off-by: Ethan Dye <[email protected]>
|
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. |
Signed-off-by: Ethan Dye <[email protected]>
|
|
||
| If you are running on a system with less than 1 GB of RAM you will likely experience issues. | ||
| You may think you can get away with less than 1 GB of RAM but you won't have enough memory to run much other than openHAB. | ||
| If you experience issues then be aware it is unlikely that there will be much we can do to help, we have been unable to figure out how to magically give more RAM to you by an update. |
There was a problem hiding this comment.
This should be more to the point:
omit l31
Mention slowness, unforced restarts and exception messages to make clear there's no single 'handle' one can check.
| For systems with 1 GB of RAM then you will probably be fine with most things and even be able to run a couple of extra components. | ||
| Your system still has limits and they will be easily reached if you get a bunch of things going to be conservative. | ||
|
|
||
| Additionally, running a 64 bit image on only 1 GB of RAM tends to result in the same situation as running on a system with [less than 1 GB of RAM](#less-than-1-gb-of-ram) so probably don't try to do that either. |
There was a problem hiding this comment.
I think given our current 64bit recommendation and looking forward to OH5/64bit, we should reword this and distinguish between existing (32bit) installs and new ones.
|
|
||
| ## Preparing Debug Logs / Reporting Issues | ||
|
|
||
| If you've tried the advice up to this point and its still failed to install, its time to dive deeper and enable debug logging. |
|
|
||
| ### Enabling Debug Logs | ||
|
|
||
| Before your first boot, you will need to edit `/boot/openhabian.conf` and `debugmode` to `on`. |
There was a problem hiding this comment.
We better skip 'on' will need maximum sooner or later anyway.
| If you are impatient, you can try and follow along with the installation logs in the web browser at [http://openhabian:81](http://openhabian:81). | ||
|
|
||
| If you want to try and salvage a failed install, you will be on your own. | ||
| The only option that we can support is a complete reinstall, sorry, there are just too many potential issues to support anything more than that |
There was a problem hiding this comment.
| The only option that we can support is a complete reinstall, sorry, there are just too many potential issues to support anything more than that | |
| The only option that we can support is a complete reinstall, sorry, there are just too many potential issues to support anything more than that. |
| WiFi requires user configuration prior to the first boot of openHABian. | ||
| For more information on how to configure Wi-Fi before first boot see [Wi-Fi Settings](./openhabian.md#wi-fi-settings) | ||
|
|
||
| If you would rather not try to do any additional configuration before first boot you can try to make use of the [hotspot](./openhabian.md#wi-fi-hotspot) feature. |
There was a problem hiding this comment.
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.
|
|
||
| ## What to Prepare For | ||
|
|
||
| In an ideal world, you should have a spare for *every* component that you use in you smart home system. |
There was a problem hiding this comment.
| In an ideal world, you should have a spare for *every* component that you use in you smart home system. | |
| In an ideal world, you should have a spare for *every* component that you use in your smart home system. |
| In an ideal world, you should have a spare for *every* component that you use in you smart home system. | ||
| This means having a backup SD card, RPi, router, switch, and any external addons (e.g. ZWave stick). | ||
|
|
||
| Since you probably won't actually do that (but you should) here are some simple things that can reduce the headache if it is simply a part of your openHABian instance fails. |
There was a problem hiding this comment.
Double-insist on a controller spare (ZWave or Zigbee stick of same model)
| Moving your system root to a USB stick or SSD is unsupported and dangerous. | ||
| Besides USB sticks in particular suffer from the same issues as SD cards. | ||
| SSD's do as well but to a lesser extent. | ||
| In summary, just don't do it! |
There was a problem hiding this comment.
I know you don't want to write this but a major reason for the harshish old text is that there's still a number of oh users that boot from SSDs and keep insisting on telling others that that would be a good idea.
While not wrong technically in itself, we know that they are neither implementing this generically nor are they supporting it on the forum that so it's always us to pick up the slack there, and I hate reading about that, it's a red flag to me.
We really must give more background info and make the reasoning clearer here, else too many inexperienced readers will again fall victim to those telling them SSDs are the solution.
| If you don't know what this means in UNIX terms, please do some internet searches now to learn more. | ||
| Your mountpoint should be a directory on your Raspberry Pi with the USB device or NAS mounted to. | ||
|
|
||
| If you are a Windows user, please note that CIFS shares are not supported and almost certainly will not work. |
There was a problem hiding this comment.
Make this more prominent again.
Again, a major reason for the existing wording is that too many people have missed this info and tried CIFS. We don't want to end up back there. The quality of this documentation is also determined by how much it keeps off ourselves,
I don't want to repeatedly read and have to answer posts on the forum when people did it the wrong way because they were unwilling or to lazy to read the full docs (which is something that'll always be the case so we must male sure the relevant information is placed first inside a section ).
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.