Creating Device Pages in LEDE Wiki

It's great to see that the dataentry templates are available. But the harder work is creating the Device Pages that give all the wisdom that people have garnered about a particular device, including:

  • full hardware details
  • finding proper firmware image
  • flashing
  • unbricking
  • hardware oddities
  • photos
  • bootlogs
  • tips and tricks
  • etc...

We could automatically import all the Device Pages from OpenWrt. We could, but that would have big ramifications:

  • We would import everything that's correct, but also everything that's incorrect.
  • We wouldn't provide any improvement to the quality of information, nor any indication that the data has been checked recently.
  • We wouldn't take advantage of some of the power available with the data plugin, especially the ability to create "tabbed tables" for information drawn from the dataentry (See the example at the top of https://wiki.openwrt.org/toh/mqmaker/witi)
  • We lose an opportunity to give a formal structure/look to all Device Pages, with a recommendation for "best practices"

Instead, I would prefer to come up with a workflow for creating LEDE Device Pages that rewards people for combing through the info on the OpenWrt page to find the relevant stuff.

I am hoping we can make a Device Page template that gives the best practice for displaying information about a device. It should include the info in the list above. It might have the format below.

We can automatically create an initial page for each device that contains the Device Name, the Tabbed Table, and a note that says, "See information on the OpenWrt Wiki, https:$OpenWrtDevicePage" with the remaining headers as placeholders.

It's easy to generate this automatically, and delivers immediate value. (The tabbed table is a good way to organize the hardware information.) As people update the Device Page, (even if they simply copy-paste info), it becomes clear that the LEDE page has been updated/vetted.

Thoughts?

sample Device Page template

Header giving Vendor & Device Name

Hardware Information (with the Tabbed Table of hardware info)

Automatically generated "See OpenWrt Device Page at https:..." A person who updates this page would remove this link to the OpenWrt page

Getting and Flashing Firmware (empty to start, but should contain narrative to tell how to do it)

Hardware Information (empty to start, but should contain memory layouts, pinouts for RS-232/JTAG, etc.)

Photos (empty to start)

Troubleshooting/Unbricking (empty to start)

Boot Logs (empty to start)

Tags (empty to start?)

I like the way unavailable information is marked on techinfodepot, e.g. http://techinfodepot.info/wiki/Netgear_R6300_v2. Different to the current OpenWrt template_device, techinfodepot only shows a small box telling the reader "This section is empty. You can help by adding to it. (August 2014)"

Why do I like this?
It doesn't "fill" the page with unavailable information
It gives an indication since when the "empty" status is present

What would be even better:
The "adding to it" link currently leads to editing the complete page. Instead, I would like to link to an example section on an example page which provides explanations and ready to copy&paste empty content.

Another nice thing on techinfodepot: Lengthy bootlogs are initially hidden (or better: folded), which saves much space and keeps the page clearly arranged.

Regarding your proposal for template_device: In general it is looking good, but there's one point I would like to see improved in the LEDE wiki: Flashing Firmware is described over and over again in each and every little detail in the OpenWrt devicepages. There are certainly devices out there that need a non-standard way for flashing, but for devices which follow a standard way of installation, we should take advantage of a modular approach, define this standard way (or ways), and then only put an include on the devicepage. Just a rough idea that needs to be further developed.

Copy&paste devicepages from OpenWrt: This needs to be a manual process, in order to achieve an improvement. Many devicepages have grown over long time, with dozens of editors doing small edits, but without looking at the big picture, i.e. the overall structure of the devicepage and the structure of the wiki itself.
Manual creation of devicepages with turned on brains helps to consolidate the big amount of information that has piled up over time.

Tagging: Although I helped to add tags on devicepages where ever possible, I ask myself: Have the tags in the OpenWrt wiki ever been of a real use? Most info available through the tags is present in the dataentries anyways. To avoid putting ressources into a feature that later on is of no real use for the wiki visitors, we should first figure out how we can use tags in a way that adds realy value to the wiki.

Yes, the "You can help by editing..." box makes it clear what to do. Plus, Dokuwiki makes it possible to edit just one section, so this seems feasible.

Another nice thing on techinfodepot: Lengthy bootlogs are initially hidden (or better: folded), which saves much space and keeps the page clearly arranged.

Huzzah! Is there a facility like that in Dokuwiki?

Regarding your proposal for template_device: In general it is looking good, but there's one point I would like to see improved in the LEDE wiki: Flashing Firmware is described over and over again in each and every little detail in the OpenWrt devicepages. There are certainly devices out there that need a non-standard way for flashing, but for devices which follow a standard way of installation, we should take advantage of a modular approach, define this standard way (or ways), and then only put an include on the devicepage. Just a rough idea that needs to be further developed.

Yes. This implies that we need really strong/clear flashing instructions. I think the reason people write their own is that a) they may be blabbermouths, but more importantly b) they're worried that the generic page won't do the trick. More specifically, I have always "felt afraid" of the OpenWrt "generic instructions" for the following reasons:

  • The page is called "generic" - so it's unlikely they would apply to my (precious, unique, and incredibly cool) router
  • The page name is some gobbledygook - "generic.flashing" - doesn't inspire confidence
  • The page name is lower-case: again, I always had the sense that it was thrown together in the early days, and most likely was not well maintained.
  • The first thing you see on that page is a death warning that you may brick your router, followed by a warning that the page is "VERY generic" and may not apply to your router, followed by four (FOUR!) different ways to flash, without any recommendation of which to choose.

I will start a new topic to talk about what should be on the "Standard Flashing Instructions" page.

Copy&paste devicepages from OpenWrt: This needs to be a manual process, in order to achieve an improvement. Many devicepages have grown over long time, with dozens of editors doing small edits, but without looking at the big picture, i.e. the overall structure of the devicepage and the structure of the wiki itself.
Manual creation of devicepages with turned on brains helps to consolidate the big amount of information that has piled up over time.

I couldn't agree more. I think the boxes with "help us improve the page" will go a long way to toward that end. Those boxes could even be customized to suggest the information that should appear in the section...

Tagging: Although I helped to add tags on devicepages where ever possible, I ask myself: Have the tags in the OpenWrt wiki ever been of a real use? Most info available through the tags is present in the dataentries anyways. To avoid putting ressources into a feature that later on is of no real use for the wiki visitors, we should first figure out how we can use tags in a way that adds realy value to the wiki.

Yes, I think of tagging as a way of allowing a human to label an item that can't be found by search. For example, HOWTO's might get tagged if they mention a topic that isn't directly related. I suspect that we don't need to add tags to the Device Pages, since hardly anyone searches for a particular SoC chip set or Flash size, and the ToH handles that anyway...

Testing, 1, 2, 3...

I'm replying via email to see how it the inserted comments appear in the forum (as opposed to clicking the Visit Topic button). You can ignore this note, since I already made substantive comments in the forum.

Subject line is: "Re: [LEDE Project Forum] [LEDE Wiki] Creating Device Pages in LEDE Wiki"

I've put <inserted comment #1>, <inserted comment #2> into the message...

PLEASE IGNORE THIS NOTE!

Oh, cool... Only my top-posted text appears in this response. No comments inserted into the body of are there (since the forum seems to omit the previous info...)

There is now:
folded plugin https://www.dokuwiki.org/plugin:folded <--- disabled again; unsure if this is the reason for the double dataentries
outliner plugin https://www.dokuwiki.org/plugin:outliner

Please check them out and let me know which one is the prefered one.

Sidenote: Nested quoting seems to be a problem for this forum, at least for the "mark & click reply" method.

Oh, look at what we have here, templating things wasn't a so original idea after all. please read my post here:here

tl:dr: basically turn all most usual flashing instructions in templates and load them automatically in device pages with device/brand-specific tweaks the same as you do with other things proposed here.

I have a very dim view of tags, I'd rather not see them around.

Tag systems tend to fill up with total nonsense tags and are another layer of mainteneance required for very little gain. Because really, why tags in a wiki, we have links, text search. Tags kinda make sense for image-based sites where you need to categorize images, but here... nope.

I'd say to disable them for good.

OK. All three of us agree - No to tags. Whew, one decision down, several hundred to go :slight_smile:

Tag plugin disabled.

I'll also mention it in this topic... See my prototype (draft, nowhere near final) template for a Device Page at: https://wiki.lede-project.org/playground/sample-device-page

It's fun to think about whether we could automatically populate the page in its entirety by excerpting info from the ToH and the dataentry's...

I forged ahead and created a real LEDE device page for the D-Link DIR 860L, based on

  • layout suggestions of this discussion thread
  • real data from the legacy OpenWrt side of 860L
  • some stuff I've added

-> https://lede-project.org/toh/d-link/dir-860l

missing:

  • haven't migrated OpenWrt Photos yet
  • tags missing (I think there is no tag plugin activated so far? https://www.dokuwiki.org/plugin:tag)
  • dmesg output from a release version is missing (I am currently running a snapshot and think, adding snapshot firmware output to a device page is not a good idea)

As for now, I'd appreciate to not create any devicepages in the LEDE wiki.
OpenWrt and LEDE wiki will be merged anyways, once the merge of both projects is official and the necessary prerequisites are fulfilled.

Having the devicepages separated in the Openwrt wiki will allow for an easier merge.
While we are merging, we should also restucture the pages, because they are a wild mix of styles, contain outdated information and are just in bad shape. But that will be a separate (long) discussion.

it's ok. have removed it in the mean time, kept a backup.

Tag plugin re-enabled again due to import of OpenWrt devicepages, which are using tags.

I'm not sure if this is the right spot, but the auto-generated pages were a bit confusing in that "old" versions appeared first. "What, discontinued???? I saw an Archer C7 on Amazon last month!" -- Well, it was v2 that was discontinued, and v4 is buried down the page quite a ways. Sorting the version sections in reverse-chronological order, and adding a section title to make it easier to wade through the mass of tables they produce, would improve usability, in my opinion.

https://openwrt.org/toh/tp-link/archer-c7-1750#info

I find the ToH firmware list easier to follow...

https://openwrt.org/toh/views/toh_fwdownload?dataflt[Model*~]=archer+c7

I now added sorting by version.

I updated the Archer C7 page to use a new template_hardwaredetailsheader that puts a header containing the vendor/model/version above each of the two-column hardware details.

https://openwrt.org/meta/template_hardwaredetailsheader

Perhaps this could update the current https://openwrt.org/meta/template_datatemplatelist

NB I couldn't find a way to make that header "stick" to the columns below it, but I think this is pretty clear.

Update: I was able to enclose both columns of data within the header's table, so this looks OK now

With an ugly side-effect: Place your mouse on the table and see what happens... :frowning: