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.
Very well put.
The documentation is one of the biggest reasons I could never force myself to stick to using Linux. I always ended up going back to Windows (which I was more familiar with, and the help system there actually provided decent assistance), and eventually moved to FreeBSD (the handbook is incredibly useful, and the man pages are full of relevant examples).
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 almost like an analog for Linux itself. However, there you have gatekeepers/managers for the kernel and various distros who then sort through the stuff before adding it to their bundle. Its a shame that documentation takes a back seat on so many things.
*ducks*
Meta will eat itself
WHAT Linux documentation?
typo: s/can/can't/
34486853790
Connection too slow for X forwarding? Try "ssh -CX user@host"
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?
But imho documentation isn't just formal man pages. Personally, I've finally stuck with Linux because of the community available today.
For specific things (e.g. driver issues), I've found myself increasingly using forums first then wikis, google second. It's amazing how good the distro forums have become because the community has become more tolerant to newb and intermediate users (well, Ubuntu in particular).
It seems that 90% of the time just searching the Ubuntu forums gives the answer I was looking for in the shortest amount of time. Also, it feels more like brainstorming with someone else which really helps the learning process. If the complete answer isn't there, then at least there are enough keyword clues in the posts to form a good google query and get into the heavy details. In the end there's almost always an answer available unlike the "old days" because the mass of the community has grown.
Having said all that, there are some wiki pages that are simply invaluable and quite a few of the good ones are for Ubuntu. Some authors do a great job laying out the steps and, most importantly, you definitely learn something along the way. Imho, ideally the wikis should be the end-all to good documentation. A well formed wiki should be tailored to both specific and general topics with a powerful search engine as the index.
As for switches and command usage, a couple O'Reilly books are always within reach. Sometimes it's just nice to thumb through a dead tree once in a while.
Funny this Ask Slashdot should come up. I was looking at some Bash guides on TLDP just today and many of them are really poorly written and in sore need of modernization in style and layout, as well as some good copy editing. As someone with a passion for good documentation and writing and an eagerness to help out the open source community, I'd gladly put in work to update some of these. Unfortunately looking through the TLDP site, it looks it's fallen in to serious disrepair. The status page for updates and reviews looks like much of it hasn't been updated in around 2 years, and it's hard to find what the procedure for updating or contributing is these days. It looks like the mailing lists are not quite so active either, and most of the few discussions there are seem to resolve around licensing of documentation and some other not quite so productive topics. Is this site even relevant any more? Is it time for some people to get together and form something new and distribute some nicer formatter, better written, and quality standard documentation?
'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?!
That would be Zwiki. Eg: http://zwiki.org/FrontPage/contents#PageHierarchy. This was partly influenced by Drupal's books.
"Wikis are the lazy or uninterested programmer's way of doing documentation."
I think most packages have good installation instructions, OK usage instructions, and no troubleshooting information. The problem isn't that the programmers don't want to write docs, it's that they have no more idea what to write than you do. Take a look at Linux sound. The ALSA wiki is the only place to go to try to find what people have done to get specific cards working or problems solved.
Intron: the portion of DNA which expresses nothing useful.
Using them for support is tolerable, depending on how well moderated the forums are.
It's more than tolerable. It's often the quickest way around any immediate problem. I've long been into the habit of (having hit a snag in any particular application) hitting Google with "stinky-finger-program error #nnnnn" and looking for forum entries. The combo is usually very helpful. I no longer want to wade through the documentation unless it relates to something I know I'll use every day.
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]
On the other hand, I find that wikis are about the only place you can get good and up to date information for large projects.
Professional ventures will often have good pure technical specification, but especially how-tos tend to get outdated rapidly, or omit things because the developers see things differently from the users.
I don't use any particular wiki either, though. They just augment my Google.
About your properly-indexed wiki idea; A lot (most?) of the distro wikis out there seem to employ some form of open license, so there would be a lot of readily stealable content. Though if you really had an such an amazing documentation wiki layout, it could be easier to just make indexes in already existing wikis.
In a fair world, refrigerators would make electricity.
The problem is when you can't find documentation other than "use the forums" which generally have a horrible search, a limited search, or NO search, so you post asking your question, and get told "we've answered this many times, go read the archives". Oh, and you have to register to post your question, so it becomes yet another login/password to forget, and yet another throwaway email address.
I don't have that kind of time to waste. As much as I can't stand wikis as a subsititution for real documentation, given the choice of wiki or forum, I'll take wiki every day of the week and twice on days that end in "y".
'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.
Google. That is the only tool you really need. Proficient googling will give you the appropriate result, whether it is contained in tldp (almost never), a wiki, a forum, some ascii file attached to a source bundle, whatever. Google indexes all those things.
Actually looking at the project page, wiki, or forum manually is a desperate and last resort and rarely yields an answer if google didnt (probably because those are all in the google index).
Linux has had documentation of dubious quality as long as I've been using it, since before TLDP. Even back in Redhat 5 days (or earlier, on old Slackware) it was a crap shoot whether you'd get a man page returned for any arbitrary command or system call. More likely than not you'd get nothing returned for third-party software, and this has not improved with the advent of package management systems. I'm not sure why Linux has had such a hard time maintaining consistent, accurate and up-to-date manual pages, but I suspect the development model is at least partly to blame. So is the lack of coherent focus on what format documentation should take (e.g. the total waste of time that are "info" pages - if it's a better format, fine - just PICK A FORMAT, ANY FORMAT and ship complete and up-to-date docs IN THAT FORMAT. Users should not have to go troll the Intarwebs to find out how to use system tools and the like.)
...)
In contrast, take a look at OpenBSD's man pages sometime - for users who grew up on Linux and haven't used a BSD, OpenBSD in particular will blow you away with the quality, accuracy and completeness of its man pages. _Every_ system command, system call and most programming artifacts have complete and well-written manual pages that ship with the system. Software from the ports tree, with few exceptions, also includes quality man pages. For those who are used to having to spend lots of time finding accurate and updated documentation, knowing that the man pages are always reliable and current is a godsend. (Not to mention the irritation of needing documentation on e.g. one's firewall software, and having to go to the Internet to find it, when your Internet connection is down due to firewall software misconfiguration
illum oportet crescere me autem minui
"If you don't like it, go make your own and show 'em how its done"
"Read the Source code"
Or do like I did - moved to FreeBSD where man pages are better kept.
For answers to specific questions, there is nothing better than google. Often, it leads me to one of the forums. I can't remember the last time it sent me to any actual documentation.
Help! I'm a slashdot refugee.
Actually, the poor state of documentation is probably one of the reasons did stick with Linux. If you have well laid out documentation, you can quickly find the answer to your question, and get on with your life. I have found that to find the answer to one question, I have to read dozens of wiki pages, many threads of mailing list archives, and ask a few questions in IRC. I may or may not have found the answer to my question, but I learned a bunch of other things, some of which will have come in useful later on.
The masses are the crack whores of religion.
Try http://man-wiki.net/ its pretty good
I've come across too many forums that are not indexed by google to rely on google finding answers held in forums.
Obviously, there are people that love forums for documentation. I hate them. We'll agree to disagree and leave it at that.
I third that! I actually do run gentoo, but my friend who runs debian also uses the gentoo docs. More or less, where the docs say to emerge some packages, you install them. And if it suggests you have to run "revdep-rebuild", be aware this indicates possible dependency problems so you might have to reinstall some other packages. Otherwise, the actual examples, setup instructions and advice are usually distribution-neutral and quite useful.
Oh come on, how hard is it to use Google.
With a simple "search item site:example.com".
You just want to piss and moan about Linux.