Following up to myself here:

What would really help would be somebody with a little experience in DokuWiki, to create a template to keep the data on the pages in a relatively reliable format in the first place. Unfortunately, this person I am not.

metai:
Now I got your angle completely.

About a unified table format for the detail pages. I'd suggest we start with one of the more popular models where usually there are quite complete tables already available and work from that to models where this is not the case.

Skimming over a few pages I identified the following table formats that seem to be recurring:
- Supported versions
- Firmware images (usually when there are different images for different revs, sometimes its also just structured text)
- Hardware highlights (a TOH-like representation of essential properties)
- Hardware info (detailed; position in article varies wildly)
- Flash layout stock/openwrt (seen different formats, the good one seen for example here: http://wiki.openwrt.org/toh/tp-link/tl-wdr4300)
- Switch/VLAN config (varying formats)

Less common (see http://wiki.openwrt.org/toh/tp-link/tl-wr1043nd for example):
- power bricks
- GPIOs
- LED config
- Hardware buttons (e.g. http://wiki.openwrt.org/toh/netgear/wndr3700)

I also noted that the organization is a complete mess. For example the order of some of the content that is structured the same way (like those tables) varies wildly.

This is good discussion!

The current list of hardware contains 890 items (unless more were added today).
I think we have to accept that the documentation will always be much better for some items than for others.

Some routers are well supported, used by many users and available for purchase - for those it will be possible to gather and maintain good data.
Some routers (or other items) are practically irrelevant for most purposes. Those ones we keep for historical and reference purpose.

Today, the signal (quality information about relevant hardware) to noise (questionable information about irrelevant hardware) ratio on the wiki is too low.

One way to proceed would be to make a poll/survey to figure out what hardware we can/should maintain information about at all. I guess it will be some 50-100 items (of the 890). Then we can find an information/documentation structure that works well for those tier-1 models. There are probably other ways to do it, but this is the best way I can think of right now.

The Table of Hardware is quite denormalized (routers that share most information are on different lines). The articles themselves though often cover several ToH-lines. I am not saying it is impossible or even hard, but it requires some thinking to link several lines to the same article, and then in one same article have different information about different routers AND making this easy to parse. I just realised this when I read your above posts.

Information that changes rarely (like specification) should preferable be kept in denormalized table form, even if it makes the table much wider than it is today.

Well, I will improve and run my update script.

Excellent progress! I have been working on another front.

I also want the top of the TOH page to help people get OpenWrt installed. (After all, that's why they went there...) I have proposed a replacement section for the first part of the TOH that:

- Tells how to install for your current router
- Gives info about selecting a new router that will be well supported
- Encourages people to update the router-specific Details page with direct links to the BB & trunk build images. That's another way to get good info into the wiki.
- Moves info about obsolete versions to the end

I have posted it at the very bottom of the TOH page (http://wiki.openwrt.org/toh/start) for your commenting pleasure. Let's keep the discussion on this forum so it doesn't clutter the info on the wiki.

(Last edited by richbhanover on 11 Apr 2015, 20:01)

I agree that there should be some indication on the detail pages if that particular model is outdated or not, maybe to create a "core hardware list" and an "extended hardware list".

Everything else besides a normalized "OpenWrt relevant data sheet" should (and, let's face it, will) be kept in an unorganized "information dump" form. There is no need to change/normalize all the information on the detail pages.

(Last edited by metai on 11 Apr 2015, 20:07)

@richbhanover: The ToH is the table of hardware, not the table of what firmware versions there are and how to install them.

IMHO we should keep the pure data (ToH) apart from instructions.

So, I have updated the compiled page:
https://dl.dropboxusercontent.com/u/906 … index.html

Here are the scripts (shell+nodejs) I use to generate the pretty HTML page:
https://dl.dropboxusercontent.com/u/906 … ikifix.tgz
(I don't think you will look at it, but since this is after all a FOSS preject it felt honest to publish it under a BSD license)

I think... installation instructions is one thing.
But it is not very trivial to find the firmware image in BB or trunk just knowing the target (form the Table of Hardware) and the hardware model. I think it would make sense to let the target column be more helpful in finding the right image.

I myself the other day could not find an image for the ASUS RT-N10P and RT-N10U. Perhaps there is some "generic" broadcom image that works? I ended up moving it from "supported" to "possible" because of this... later I realised that maybe it was a mistake? I don't now.

Because the target column is not mostly there to help people who use buildroot to make their own images?

Since I am talking about the target column...

6        Infineon Amazon
1        Solos 461x
1        gemini
1        UR8
1        Fusiv
1        powerpc
1        brcm
1        Mindspeed

I think the only permitted values in the target column should be things found here:
http://downloads.openwrt.org/snapshots/trunk/
I don't think the ToH should invent targets like "Mindspeed" and "Fusiv" that may never materialize.
Can we replace all such fake targets with "no target"?

But it would be a nice and useful addition to the overview if you could see at a glance if a device can be flashed through a factory firmware update/flashing method (easy), through TFTP/UART (advanced) or other means (experimental).

Also, I would suggest splitting up the "supported" data. First of all, it is too cluttered/diversified. Mostly it means "supported since" and an OpenWrt version. But there's a lot of nondescript "trunk" in there which in many cases means a trunk version of 12.09 and hasn't been updated since. And then there's the revision number which is of no use to someone who's not closely following OpenWrt development, it should go into a separate column or left out in the TOH.

(Last edited by metai on 11 Apr 2015, 21:17)

As for renaming the wireless column to '802.11 protocol', the 802.11 protocols do not apply to wireless alone. There is 802.11q as well e.g., for VLANs and a slew of other standards under 802.11. It would be technically incorrect to use it to refer to wireless alone.

Apart from that, most casual users won't even know what 802.11 entails - or that in this case it would apply to wireless protocols. Just keep the title at 'Wireless' or something similar. You don't need to put 802.11b/g/n/ac everywhere, regular users know what b/g/n/ac means even without the 802.11 prefix. They're not interested in what the number does.

Also, I am all for standardising and templates to build a better page layout for e.g. the model specific pages, and I agree with metai about providing as much useful information as possible (at least on the model specific pages). The Table of Hardware overview can be concise, however, I would still mention:
- Gigabit or Fast Ethernet switch. We might assume 5 ports (pretty standard nowadays?) and only mention the amount of ports if it deviates?
- supported wireless protocols and the amount of radios.

A thought on the wireless details: keep in mind e.g. 802.11n is both 5 and 2,4 GHz so someone looking for a 5 GHz 802.11n router cannot filter on that. If it is mentioned in the overview, it might get a bit busy though...

(Last edited by Borromini on 11 Apr 2015, 23:38)

Right, busy. And looking at http://wiki.openwrt.org/toh/start?&#tp-link we have an endless seeming list, that can not be viewed in full width without scrolling.

Luckily, Dokuwiki has plugins that ease our task auf automatic creation of the ToH:

https://www.dokuwiki.org/plugin:bureaucracy
https://www.dokuwiki.org/plugin:data

Example:
https://www.dokuwiki.org/dokuinstall

Example data page:
https://www.dokuwiki.org/dokuinstall:openwiki.kr

Maybe this could do the job.

@tmo26 I do understand your concern: we shouldn't repeat info needlessly (DRY principle.) I would ask you to help address the concerns that I have:

My motivation here is to make it drop-dead simple for a person who hears that "OpenWrt is great!" to come to the site, download the right firmware, flash it, and be happy.

The OpenWrt project is a major triumph. It is no longer experimental. You all have produced a powerful, flexible, robust, supported replacement for stock firmware that can improve life for millions of people if they could only use it. [1]

But here's the current reality: When people get to the OpenWrt home page, the first link they see is "Supported Devices". They click the link, and the next thing they see is a description of unsupported devices, followed by a description of the limitations of the Attitude Adjustment build from two years ago, and then some mumbo-jumbo about adding devices to the table (that they haven't even got to yet.)

I believe that new people are our most important use case, since helping them out increases our user base. Experienced people do need to know the additional info, but they're already tuned in, and know how to navigate the site.

My revised proposal:

• I continue to believe that individual router detail pages should be responsible for the basic info that newbies need: links to firmware and installation steps. This is important because:
  

  • @zo0ok has said that it's not trivial for people to get firmware images. I agree: Let's not create a maintenance hassle by requiring zo0ok (or anybody else) to know everything about every router and the proper image.

  • Instead, put the burden on the people who actually own that model, and (presumably) are using it. It's a wiki for goodness sake - let's exploit its power...

  • It's self-regulating. If the router doesn't have any fanatics who'll update the wiki, then that model is not popular/important enough to warrant a newbie's attention.

• I would even advocate - if there's consensus - that we mark a router's page that it's missing info and that it should be improved. (Like what wikipedia does with its "This article needs additional citations..." flags.)

• I'm not wedded to a description of BB vs CC on the main TOH page.

• I would be happy to help rework the OpenWrt top-level pages to make them much more welcoming to beginners.

But in all cases, we should make sure that the major pages of the site help new people easily get the info they need.

Thanks for listening...

[1] PS I'm a new contributor to OpenWrt, but have been following and contributing to the CeroWrt project and site for the last three years. CeroWrt wouldn't exist without the enormously powerful engine behind OpenWrt, and I am forever grateful to you all.

@zo0ok: I agree. That's why I advocate emphasizing the router details page. We should encourage people who own those routers to add specific info (my favorites are links to BB & CC images and Install Instructions) to those pages so that people can use the information to get started. We could even come up with a standard template for that info so that programs could collate it and enhance the TOH page.

If a router is not popular/irrelevant, then its router details page won't be updated. This is a signal (to people and scripts) that it isn't important, and that it isn't critical to get its info exactly right.

I'm less worried about the denormalization: if there's a router description page on which to hang unique info, then it'll be easy enough for real people to find.

@richbhanover: I read your suggested introduction draft that you put in the bottom of the ToH. I think it is mostly good!

I think however that maybe it would make more sense to put that information on the very start page (not the ToH):
http://wiki.openwrt.org/start
...and keep the ToH dead clean. That said, the information about how to update it and things like that, perhaps can go to the bottom of the page or be compacted.

This thing about avoiding devices that say 12.09 and 10.03... I am not sure about. IF there is a 12.09 device that has 32 or 64 MB or RAM, and WiFi works, and it is available for purchase, then I suppose that is perfectly fine. Now, perhaps those devices are rare.

OK. I see that point. But perhaps I should have asked this question before jumping in.

I often hear people say that "OpenWrt is scary. It's too hard to get started." Is this a concern to the group? Do you agree with that sentiment? Do you think that the site needs to be better?

(Last edited by richbhanover on 12 Apr 2015, 13:30)

This DOES the job!

I'm experimenting with the above plugins in my own dokuwiki and I'm really excited how easy this can be used!

For testing purposes, I now need the full data from https://dl.dropboxusercontent.com/u/906 … index.html (all 891 lines) converted to one file per line item, named start.txt and placed in a folder named like the model of the router.

Example: /var/www/dokuwiki/data/pages/toh/d-link/dir-677/start.txt:

====== DIR-677 ======

---- dataentry ----
BRAND         : D-Link
MODEL         : DIR-677
VERSION       : 0.99
PAGE          : supported
STATUS        : WIP
TARGET        : ?
PLATFORM      : ?
CPU MHZ       : 666
RAM MB        : 128
FLASH MB      : 16
WLAN HARDWARE : ?
WLAN STD      : b/g/n
WIRED PORTS   : 5
VLAN CONF     : Yes
USB           : 1x 2.0
----

Since I don't know how to accomplish this: Can someone more knowledgeable than me jump in and do this for me?

Purpose: I would like to see the performance of this solution and how much load it implies on the server. Therefore: Test the ToH creation with all currently known devices.

I'd be glad if someone could jump in here and help with the creation of the test-data.

OMG, YES!

When I started with OpenWRT some 2 years ago, it was a PITA to get started, find the right image to flash, then afterwards find out how to configure everything... Jumping from this page to that page, having 2 dozens of pages opened in the browser...
I found it confusing and horribly time consuming back then.

The information is all there, everything you need to start and get things going. However, it's hard to find certain information, unless you know where and how to seek.

I will start working on it in a few minutes.

For your information, the raw data is in:
https://dl.dropboxusercontent.com/u/906 … toh_all.js

...so it is easier than you think to convert it to your format

But that is no excuse for me, to not do the job. I will gladly fix it.

Edit1: I am tempted to rename PAGE to OLDPAGE or CLASSIFICATION or something. Let me know if you think it is a good idea, otherwise I keep PAGE for now.

Edit2: Do you need to folder names to be exactly matching BRAND and MODEL? In that case I will get rid of SPACE and SLASH.

(Last edited by zo0ok on 12 Apr 2015, 14:08)

Everyone: updated
https://dl.dropboxusercontent.com/u/906 … index.html

tmo26: created
https://dl.dropboxusercontent.com/u/906 … 54012A.tgz

It was a little nasty with the filenames... I had to deal with <=>?,é()? and probably more...
I had to add the version to the filename (folder) to make them unique.
In the case of Qemu I also had to add the platform.

I also deleted some D-Link duplicates that caused me trouble... how I didn't get in the way of someones work

tmo26, let me know how this works out and if you need it in a different way. Now it is very easy for me to adjust or regenerate.

That's incorrect. Actually there isn't a 802.11q for exactly this reason, see http://www.ciscopress.com/articles/arti … p;seqNum=3

802.11q Not used, to avoid confusion with 802.1q VLAN trunking.

We can agree on only naming the letters (a/b/g/n/ac) since the 802.11 is redundant.

I don't think anyone wants to drop the wired speed or the number of ports, both of which are useful. And while 5 ports (4+1) is pretty common on routers, there are models with only a single port, which are often used as travel routers.

A 802.11n router supporting 5GHz also supports 802.11a, so the user would have to check for a and n.

While that doesn't change the conclusion, that is a dangerous assumption imho. For example the WRT1900AC has a pretty bad wiki page at the moment, despite the model getting a lot of attention. Of course it's also not a model I'd recommend to a newbie right now, but that's yet another story.

That gets my vote.

About OpenWRT being hard:
I can somewhat agree with that. The main issue is that while basically everything is possible, configuring some things has to be done on the CLI due to lack of functionality of the web interface. Especially for people lacking general Linux CLI experience that can be scary.

I agree... that OpenWRT is a bit hard.

If, when a new release is out, we could make people update the article of the router with their "success story" (or what fails)... then the absence of editing would be a good indicator that something is ill-supported. If we are to discuss the hardware articles themselves sometime, then I think this would be a relevant thing.

Or a poll/survey.

The target column... I am quite happy with it now.

brcm-2.4 brcm47xx: I like the Warning Notice about 16MB devices with brcm47xx target may be better to install 10.03.1 and brcm-2.4. So from my perspective we could remove the brcm-2.4 information. But perhaps then people are tempted to install brcm-2.4 on routers that never were supported by 2.4.

ramips: can someone explain what is going on? The folder structure is not the same in BB and trunk (and BB makes more sense, to me). In trunk many targets are hidden in generic. These seem to be important targets. Why are ramips put in one folder/target, while mpc are allowed to have several targets with almost no supported hardware. And Broadcom. I would be fine with:
1) getting rid of the ramips thing, and let all subtargets be real targets (at root level)
2) committing to either the trunk or the BB subtarget structure
But I don't know anything about ramips. And I don't intend to ask the hard working developers to change stuff just so it gets easier for me to clean up a column

Another thing... I don't really know what tmo26 is up to, but it seems interesting and promising.

Today we have 5 tables (supported, wip, possible, unknown and unsupported), all divided brands. This has the following bad consequences:
1) Occasionally the same device ends up in more than one list
2) When searching for information about a particular model, you need to search through several pages
3) We have some kind of meta-discussion about what "supported" means.

If we had one big list (or one list per brand), with all levels of support, it would be much easier to find a piece of hardware, and easier to maintain things. Then we could have column information about "what works for what releases".

But perhaps tmo26 has a better plan.

Guys, the dokuwiki plugin "structured data" is it.
The ToH is one big list, automatically created, containing all devices.
On top of the list, you have a line with input fields for each column.

Let's say, you are searching for routers with 802.11ac -> you enter "ac" in the respective column, press enter, and there you are.
You are searching for a router with 2x USB, doesn't matter if 2.0 or 3.0 -> enter "2x" in the respective column, and there you are.

And so on, for each column.
A very convenient way of filtering.

Where does the data in the ToH come from?

That's easy: Simply add the following "dataentry" to the detail pages we know already today, e.g. http://wiki.openwrt.org/toh/d-link/dir-505

---- dataentry ----
BRAND         : D-Link
MODEL         : DIR-677
VERSION       : 0.99
PAGE          : supported
STATUS        : WIP
TARGET        : ?
PLATFORM      : ?
CPU MHZ       : 666
RAM MB        : 128
FLASH MB      : 16
WLAN HARDWARE : ?
WLAN STD      : b/g/n
WIRED PORTS   : 5
VLAN CONF     : Yes
USB           : 1x 2.0
----

This dataentry will be shown as a big table, wherever this dataentry section is placed on th page.

I try to setup a demowiki, to show you how it works.
But anyway: We need the "structured data" plugin (+php5-sqlite) installed in the OpenWRT wiki! Who can do this?

What needs to be done:

OpenWRT Wiki-Admins:
- Dokuwiki: install "Structured Data" plugin -> https://www.dokuwiki.org/plugin:data
- Dokuwiki: install "sqlite" plugin -> https://www.dokuwiki.org/plugin:sqlite
- sudo apt-get install php5-sqlite
- done, structured data plugin should work now.

Community:
- create new ToH page using "Structured data plugin" syntax (that would be 4 lines)
- add the "dataentry" section to all pages.

Why the whole effort of installing a new plugin?

Because creating a ToH that can be filtered is so f***ing easy with this plugin!
It's really helpful and adds value to the ToH.

Installed. Very quick test at http://wiki.openwrt.org/meta/playground/sd