Slashdot Mirror
Fragmentation in Linux Documentation?
twilight30 asks: "While trying to figure out why a supposedly-supported SATA-II controller isn't recognized on my motherboard I thought I'd go back and visit the Linux Documentation Project's pages. It was a trip down memory lane, but I soon wondered about the state of many of the documents there. Much of TLDP is old, maybe even crufty. So, I'd like to ask what you think of TLDP.org and its 'competitors'. Do people get info from other sites or Wikis? Are people more likely to look at their distro's forums first? Are distros good enough now that TLDP is basically irrelevant? For the BSDheads, do you think the BSDs' documentation pages have lessons to teach TLDP? Is TLDP still relevant to you? If not, what would have to change for TLDP to become relevant again?"
Wikis suck for documentation. Instead of a few people intelligently thinking how to lay out the documentation for a system, you have dozens or hundreds of people laying things out according to a whim. I have found good documentation on wikis, but it has always been by chance or search engine, and I can never find them again.
Or maybe I am just too rigid and structured to deal with information that isn't.
Now, if some enterprising soul set up a table of contents and a wiki with an automatically generating index and let the community fill it in, we'd have a good repository.
The masses are the crack whores of religion.
But not anymore. I frequently use it for historical documentation or if I want to know better about some topic. But when a device doesn't work, or I need a quick howto, I go over to Gentoo wiki or their official docs which are of a high quality. I don't have any doubts that the ubuntu/fedora/suse crowd check out their relevant documentation rather than head over to tldp. There are several reasons for it.
We have a lot of popular distros that do things in their own way. For example, the commands that work in Fedora will not work in Ubuntu without changing paths, package names etc... Its always favourable to have distro specific pages that allow everyone to copy-paste the commands without messing up on the fine details.
Secondly, I view whatever tldp has as a very good source to learn something. The information there is presented in a very generic way, and very well laid out - for example read the software raid howto over there and tell me whether you'll see that quality elsewhere.
But in this day of n00bs switching over, wiki pages are the way to go for popular information. Afterall, its the "in" thing now, has the web 2.0 touches and appeals to a very large crowd. The bottom line is that tldp isn't dead, just that its roles has changed a great deal in the last 5 years.
Microsoft: "You've got questions. We've got dancing paperclips."
Try your motherboard model number and some combination of SATA, SATA II, Linux.
Don't forget "blog search" if "web search" doesn't get you what you want.
Also, when you figure it out, give something back: post the solution someplace. Anyplace.
*ducks*
Meta will eat itself
Wikis suck for documentation.
I've seen documentation from about every single major IT vendor on the planet and there's one thing I can say with great confidence. Wiki documentation for Ubuntu Linux is at least as "good" overall as any I've seen. I can't count the number of times I've tried to follow documentation to the letter from many vendors only to find the wheels come off in the middle of going through a process. To be fair, I've run into the same thing with Ubuntu Wiki documentation, but no more than commercial vendors.
This problem has nothing to do with the "Wiki style" of editing. As you (indirectly) said: The more people that are involved, the harder it is to maintain consistency. This is true for *anything* Despite all the bellyaching, Wiki software is a very useful tool. It is not the tool's fault if it is used for the wrong job or is not used properly.
That said, I think Wiki software *is* the right tool for this job, but it must be used correctly. Put proper restrictions on who can edit the pages. Draft standards for layout and format and *enforce them*. And, of course, a framework of some sort (ToC as you suggested) would go a long way towards an organized and usable documentation archive.
=Smidge=
Wikis are the lazy or uninterested programmer's way of doing documentation. Why do the "boring" part of telling people how to use it when you can set up a wiki, tell everyone that the answers are in there, and let your users write the documentation for you?
Even worse than wikis though are using forums for documentation purposes. Using them for support is tolerable, depending on how well moderated the forums are.
Like you, the lack of good, current, and well-organized documentation is one of the reasons I don't use linux, but I'd argue that the problem goes beyond "linux" and is a problem that most open source projects need to solve. There are exceptions, of course, but the fact is most open source advocates are programmers first, and writers second (if at all).
* twilight30 has joined #linux-help :)
<twilight30> Hi guys. My SATA-II controler is not recognized altough it is officially supported under Linux. Any idea ?
<l33tn3rd> RTFM n00b !
<twilight30> I would be glad to read it if only I could find it
<l33tn3rd> STFW l0ser : http://www.tldp.org/
<twilight30> Already been there. It's outdated and I haven't found any valuable piece of info. Any idea ?
*** l33tn3rd sets mode: +b twilight30*!*@*.*
*** twilight30 has been kicked my l33tn3rd ( STFU n' get BSD u moron ! )
<l33tn3rd> lol pwned !
<ub3rg33k> fucking n00bs. Oh btw hav u seen the last Natalie Portman vidz on youtube ? ROFL !
<l33tn3rd> lol got the complete vidz on torrent
Doesn't the documentation automatically get defragged every 30th time you read it?
'cause nobody would write the documentation anyway.
If there is a wiki there is at least one places where info are supposed to be.
If you can't find them you can bug the programmer once and then add it so that those who will follow won't have to do it over and over again.
Instead of a few people intelligently thinking how to lay out the documentation for a system, you have dozens or hundreds of people laying things out according to a whim
That's terrible, unless you don't have a few people who want to intelligently write a manual. Wiki documentation is better than no documentation.
In the days before Wiki, I ran a FAQ-O-Matic. Having people do the editing was great, but I had to put in effort as a benevolent dictator to keep it neat and meaningful. Jon Howell had a great thing going, but ultimately, it was too hard to move from one machine to another, and I haven't seen a new release in years. It would be nice to have a mode in a Wiki that enforced a hierarchical structure like FAQ-O-Matic did, for certain classes of data.
It's hard to tell if the contents/chapters/index model is the right one for a manual, or just something we're all used to with half a millennium of momentum behind it.
My God, it's Full of Source!
OUTSIDE_IP=$(dig +short my.ip @outsideip.net)
I'm sorry, but distro forums (Ubuntu's, at least) aren't very useful. Every time I need to Google to resolve an issue, the top link is to an Ubuntu forum. Someone's laid out the question clearly and concisely, and is either ignored, or is told "RTFM".
It bears mentioning again: The questions were worded well, with important details provided.
tasks(723) drafts(105) languages(484) examples(29106)
You mean, Linux has documentation that isn't a man page or a '-h' switch?!
I second the parent and sibling post. Many times I've had to plow through Linux docs, and consistently find straightforward answers in the Gentoo wiki. They give usable examples, and it's something that can be used by most Linux distros, not just Gentoo. Yes, there are a few places here and there where the Gentoo wiki tells you how to compile with certain flags, so that's not for me since I use precompiled binaries (Kubuntu / former Mandrake), but most of the time it's a treasure trove of info. Thanks, Gentoo wiki!
404555974007725459910684486621289147856453481154 in hex is "You sank my Battleship?"
[GPG key in journal]
'which generally have a horrible search, a limited search, or NO search'
Google is the only search. It indexes that posts in that forum along with everything else. Google is the best documentation and helpdesk I have ever found.