OpenWrt Forum Archive

Topic: The online documentation could be *much* clearer.

The content of this topic has been archived on 6 May 2018. There are no obvious gaps in this topic, but there may still be some posts missing at the end.

As someone who, a while back, tried to figure out how to get OpenWRT onto a Linksys WRT54GL, I have to say that the online documentation leaves quite a bit to be desired.  By way of demonstration, let me explain what I went through trying to figure out how to do that initial installation.

First, I checked the Supported Devices table, where I found the two entries related to the WRT54GL, both of which refer to the "Broadcom 5352" platform.  But I happen to know that the CPU model of my V1.1 router is "BCM3302 V0.8" (as subsequently listed by "cat /proc/cpuinfo").  So how do those two pieces of information relate to each other?  If I was a beginner, I'd be wondering if this was even possible anymore.  Does this represent a model of the WRT54GL that doesn't support OpenWRT, I'd be asking myself?  How would I know?  And it gets worse.

At the kamikaze release page here -- http://downloads.openwrt.org/kamikaze/release.txt -- I'd like to know if my router can handle the latest version of kamikaze.  But what I read is:


brcm-2.4 - Broadcom devices requiring Broadcom wifi
                 (everyone migrating from Whiterussian)

brcm47xx-2.6 - Netgear WGT634U, Broadcom Devices without Broadcom wifi
                 (you can use this instead of brcm-2.4 but wifi won't work)

But, again, if I'm a beginner, what does any of that even *mean*?  If I'm a beginner, how would I know if I have a Broadcom device that does or doesn't "require" Broadcom wifi.  How would I be able to tell?

Based on my perusal through the online docs, I'm willing to believe that the information can be found *eventually*, but it's certainly a slower and more painful process than it has to be, particularly if you're targeting beginners who don't have the necessary technical background.

Documentation is bad.  I don't think you'll get any arguments on that.  But then, I am fully aware this is not uncommon for any open source project and documentation is usually the lowest priority.  Also, being in an engineering discipline, I know good technical documentation is a very difficult thing to do requiring talent hard to find.

The technical details of Broadcom "entities" doesn't help.  Open your box and I'm pretty sure you will see that "5352" stamped on the part.  Problem is what's inside a "5352" is a bunch of modules including a CPU with it's identification, some wireless module with it's own ID, a switch with another ID plus a bunch of stuff I never fully looked into.

Somewhere in the world there may be resources to sort all this out but remember Broadcom doesn't help much.  Then, if some list were to develop of all this info by someone's hard work to compile it, it'll be obsolete with the next version.

I'm not trying to support or defend.  Just trying to state facts.  All comments welcomed.

Believe me, I know how difficult documentation can be to write -- I sort of make a living at it, and it's depressingly easy to get so busy, you can't go back and bring stuff up to date.  I just wanted to point how even the intro-level stuff at openwrt.org might leave beginners a bit baffled.

Also (and while I'm here), it would seem that the content here:

http://downloads.openwrt.org/kamikaze/release.txt

which discusses which devices support Kamikaze doesn't seem to match the content in the "Supported Devices" table.  That first URL suggests that, for instance, the AMCC Taishan supports Kamikaze, while the status in the Supported Devices table is "Supported", which is defined as supported by WhiteRussian, not Kamikaze.  Perhaps those two pages could be brought into sync by someone who knows all that stuff.

The thing with the documentation will never change in near future.

Just my two cents.

Um ... while I'm here, let me wander briefly off-topic.  All of this was in aid of my trying to figure out what I could use for my in-home network that was 2.6-based (currently running whiterussian on that WRT54GL I mentioned).

As i read it, since I currently have no desperate need for WiFi (everything is within short cable distance), I can reflash my linksys with brcm47xx-2.6, which will give me full Kamikaze but absolutely no wireless, is that right?  For me, that would be just fine for now.  I just prefer to have everything here running 2.6, for consistency, and I'll worry about what to do down the road when wireless becomes necessary again.

So ... is the above an option?  Thanks.  I will stop whining now.

rpjday: Read the documentation.

Um ... thanks ever so much, whbjr, for that utterly vacuous and valueless response.  You will, of course, note that I originally wrote, "As I read it ..." and even linked to the appropriate page that I had found, from which I reproduced the relevant text:

"brcm47xx-2.6 - Netgear WGT634U, Broadcom Devices without Broadcom wifi
                 (you can use this instead of brcm-2.4 but wifi won't work)"

and, since we had already determined that some of the documentation sometimes just can't keep up with the development efforts, I thought I would just play it safe and and ask if that really meant what it *seemed* to mean, just so I didn't misinterpret it and brick my Linksys or something.

In other words, a simple "Yes" on your part would have sufficed, rather than that snotty, condescending attitude, know what I'm sayin'?

I'm hoping others on this forum will be significantly more helpful.

Well, we could have a documentation day.  Anybody up for it?

I'd be willing to help, but it would have to be planned carefully ahead of time.  That is, what exactly would people be expected to do?  And how would all that incoming information be processed?  And by who?  I'm not sure letting numerous people loose on the wiki is the most productive approach.  Suggestions?

You could just go ahead and pick a "child" in the wiki you would like to update and nurture into the future - or if you would like to make a draft of a template for hardware entries this would be appriciated (it would be really good to have a much more uniform structure across the intries in the TableOfHardware) ?

I would like to help to but never got response on my application. Best thing is 1 supervisor would post the how to's on the wiki.

Documenting documentation.  Love it! smile

I really think a disservice was done when not-close-to-ready Kamikaze documentation replaced not-nearly-as-bad Whiterussian on the Wiki.  I cut my teeth with Whiterussian and the documentation wasn't nearly as bad at that time.  If the opportunity exists (it may be too late) I suggest parsing out the Whiterussian docs in a separate tree/archive.  I do not understand why Whiterussian, a mature but (officially) unsupported gem of a release was so quickly tossed aside.

(Last edited by Bill_MI on 6 Dec 2007, 18:52)

the dev's have made it fairly clear, white russian is waay behind kamikaze in terms of develompent,
i hate to say it but, honestly if there is deficiencies that you see that bother you, why not correct them, this horse really has been beaten to death.  No one will argue the documentation needs work, and that white russian despite thier (the dev's), reservations  is a fairly mature platform.  The other alternative (instead of complaining as all this does is irratate the others in the community) is to check out the IRC channel and politely seek assitance there.  Or you could just dig, read, break things and repeat, which is how I learned, and I will say that while painful you learn quite a bit.  Just remember to take detailed notes on your experiences and put  it out there to help others. 
I think the everybody adopt an article page is a good idea as well.

(Last edited by 22bsti on 6 Dec 2007, 20:27)

Hello, I need help!!!

i have a wrt54gl v1.1 and i installed qos package. i wrote "ipkg update" and "ipkg install qos-scripts" bu now i want to prove with the Qos parameters... modificate this attributes and i don´t know what i must to do.

Dear Gentle-People

Several very important comments have been made in regard to the status of the present documentation. It is correct that there is a "bit" of confusion in respect to WhiteRusian and Kamikaze doc's - and it is requirered to do something about this. There are also numerous other tasks.

And yes - if you need someone to scream at, someone to "aim your" frustrations at, someone to help you with pointing at where to begin, someone to ask you irritating questions, someone who listens to your suggestions (and forgets minimum half of them), someone who can create confusion in your thoughts, someone who's also interested in helping openwrt take over the world - THEN, feel free to make an attempt at 'catching me in a corner' or just send me a ping, I'll try to respond as good as I can.

But, for the sake of whatever god, cosmological entity or idiology you believe in or base your life on, decide I what way you think you can participate - instead of pointing at all the stuff which is lacking - and then do something about it.

You have already invested a lot of work - why not continue with a draft of what such a page should look like/have as content. Either make a new page in the openwrt wiki (or in your own wiki) or post the suggestion on the -devel mailing-list. It would not be a problem to "move the page to its correct position" at a later pont in time (there is a server platform on its way so a lot of 'moving and merging' has to be done anyway).

Personally I would really appriciate it if you went ahead, and help in what way I can.

OK, give me a couple days.  I'll be in transit this weekend.

A sticky thread for general questions and comments about docs on the wiki might be useful.

rpjday wrote:

OK, give me a couple days.  I'll be in transit this weekend.

Take the time you need ;-)

The discussion might have continued from here.