RFC: Installation instructions + ToH

Talk about Documentation
1

Current situation

Currently, installation and recovery instructions are repeated over and over again on each devicepage (if there is any devicepage for your specific device). Each time different, but always describing the same procedures.

Thinking of making the instructions more modular, I added new datafields for installation + recovery method to the dataentries back in 2018:

grafik
grafik.png701×211 15.6 KB

Since the pages behind the links did not exist until now, they were shown as non-existing pages. Not very helpful for the users.

Todays changes

Today I added the detailed pages for installation + recovery methods, i.e. those links are working now (mind the different color):

grafik
grafik.png705×211 15.5 KB

Why new datafields for installation / recovery?

Q: Why do we need those new datafields?

A:

  • To make it easier for the user to find out the installation method for his device (via dataentry or ToH), even if there is no devicepage yet available for his device
  • To move one step closer to modular installation instructions, which can easily be linked from dataentries, ToHs and/or devicepages.

Why separate pages for installation / recovery?

Q: We have already pages describing TFTP installation, Sunxi installation, Mikrotik installation, ... why do we need extra pages now?

A: To make the links in the dataentries / ToHs work, all instructions need to be in one namespace. For this tryout, these are inbox/docs/installation/ and inbox/docs/recovery/ (final location after tryout still to be decided)

The new pages are currently mainly meant as a stepping stone, bridging the gap between dataentries and already existing installation pages. In the long run however, one could think of moving the content of the existing installation pages into the new ones, in order to have one place for them, not many.

Inbox status

As you can see, the pages are currently in the inbox, meaning they are WIP.
Some of the pages are already quite OK (IMHO), others are a mere placeholder / skeleton which still needs to be filled (your help in filling those pages is appreciated).

Please tryout

To tryout this new functionality, see the pages below and click around on the different options.

Please comment

I'd be happy about your feedback regarding this proposal!

  • Good idea / bad idea? (Why?)
  • Needs changes / improvements (which?)
  • ...
3 Likes
2

It might work to collate the procedures by the different vendors (assuming they have rather unified recovery methods), but I feel trying to generalize those would be more complex (different settings, methods) and at the same time making it harder to beginners to follow the advice than keeping it splattered over multiple device pages.

E.g. TP-Link and ZyXEL both pull recovery firmwares from a tftp-server (different IP's mandatory, different filenames), while e.g. Netgear and Buffalo require the user to push the recovery with a tftp client for push-button tftp recovery. Listing all the peculiarities and then referring to generic info isn't much shorter/ more helpful than 'open coding' the specifics in the relevant device pages.

3

Looks nice to have all the installation and recovery methods in one place. I believe this way it will be easier to find what you want.

1 Like
4

I like how you've tweaked the datatemplate to pick up these various installation/recovery methods. I've forgotten where it stands - is there a default template for a new Device Page? (Obviously, it would be good to have a standard way to display those methods...)

Also: as a partial attempt to collect information about the differences between Failsafe, Factory Reset, and Recovery, I wrote: https://openwrt.org/docs/guide-user/troubleshooting/failsafe_and_factory_reset

I haven't thought deeply about how this could be tweaked to support the new datatemplate. Thanks.

5

Sweet.

Someone with a good grounding can really appreciate the clarity and structure manifesto withino.....

Suspect 80+% of visitors will slide through in a frenzy looking for "their fix"

Therefore.... Using those tables, with good device / partitioning tree navigation....

TPLINK > TPLINK General ( template driven ) > Device Groupings > Grouping page "open coding"

Two other points.

In each procedure.... near the notes.... a WHAT AM I DOING WRONG... sections might serve to cut down on panic posts....

Similar, highlighted tables/framed paragraphs.... on device specific pages might also be of use....

It is probably not the best way...... but something like "use the word hotdog" or "post a link to this page" when visiting the forum for help..... But first.....

  • Were you following instructions for your exact model

  • Did you visit the WHAT AM I DOING WRONG page

  • Did you visit the BEGINNERS GUIDE to modding page

etc. etc.

So, basically "linking the broad info > user needs" clearly and targeted from both ends in.... the info they NEED, and the info they need of that makes sense.