As @tmomas pointed out in Creating Device Pages in LEDE Wiki, we need to find a way to encourage people not to re-write the flashing instructions, again, and again, and again, and again... Not only is it boring to read, but it introduces little errors that people propagate across Device Pages.
In that same note, I listed several reasons that I ignored (and hated) the OpenWrt "generic flashing" page. Let me re-cast those points as positive attributes for our new instructions page.
- The new page should inspire confidence. Their first flash is a very anxious time for new users. They're about to take their functioning router and change it. There's a non-zero chance that they won't have a working router, so they need to be reassured.
- The page should offer clear guidance for the most common cases. It definitely needs to address upgrading to LEDE from factory firmware. It should also cover upgrading from OpenWrt, or earlier LEDE firmware. Relegate other cases (FTP, TFTP, JTAG, mind-meld) to some other "Alternate Flashing Methods" page.
- The page's heading should be a powerful statement that this is the way you do it. I propose "Standard LEDE Flashing Instructions"
- The actual page name (in the URL) should appear authoritative. I propose that contain something like "StandardFlashingInstructions". (In OpenWrt, it's "generic.flashing", which always made me think that it was written in 10 minutes, and no one took the time to write a better one.)
Other factors that I'm not so sure of:
-
The page needs to address upgrading factory firmware vs upgrading LEDE/OpenWrt. It should refer people to both URLs in the dataentry for the firmware images.
-
I have the impression that some devices need different steps for flashing over factory firmware. For example, I have a vague understanding that some devices require you to install some funny firmware before you can flash OpenWrt. For these devices, the Device Page might need additional instructions.