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."
WHAT Linux documentation?
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
You mean, Linux has documentation that isn't a man page or a '-h' switch?!