Trying to edit the docs to match the behavior

Talk about Documentation
1

I'm about to upgrade a Linksys MR8300 from 22.03 but the documentation could use some clean up as some of the language is ambiguous. I'd edit it myself, but I don't know what is right.

  1. The biggest issue is that after the first step (increase the kernel partition), the second step instructions say to use the sysupgrade image, but neglect to mention that if you try, Luci will pop up a big warning message telling you to use the factory image.

    The device is supported, but this image is incompatible for sysupgrade based on the image version (1.0->2.0).
    Kernel partition size must be increased for this OpenWrt version. Before continuing, you MUST issue either the command "fw_setenv kernsize 500000" from the OpenWrt command line, or "setenv kernsize 500000 ; saveenv" from the U-Boot serial console. Instead of the sysupgrade image, you must then install the OpenWrt factory image, setting the force flag and wiping the configuration. (e.g. "sysupgrade -n -F openwrt-squashfs-factory.bin" on command line)
    Image check failed.

    The uploaded image file does not contain a supported format. Make sure that you choose the generic image format for your platform.

So, it seems like the documentation should tell people to use the factory image, except there is a sentence in the docs which makes me think perhaps the factory image doesn't always work:

From OpenWrt 22.03 flash a 23.05 or 24.10 (or snapshot) sysupgrade image. If you are running 22.03.3 or above, you can either flash a factory image.

I interpret that to mean that before 22.03.3, a sysupgrade image was required.

There are also vague hints in the docs that 22.03.4 cannot be used to upgrade to 23.05/24.10 at all. For example, the sentence, “You need to have any 22.03 (not 22.03.4) already installed.”

It seems like the simplest method that is sure to work would be to advise people to upgrade to 22.03.5 (or later) first and then to use the factory (not sysupgrade) image, right?

  1. Another issue: Using the factory image from within Luci also pops up the "image file does not contain a supported format" error, but I think that is simply because a factory image lacks metadata.

Am I correct that the documentation should tell people it will be necessary to check the "Force upgrade" box? (And uncheck the "Keep settings" box, of course.)

Thanks.