Beta
×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Fragmentation in Linux Documentation?

Cliff posted more than 7 years ago | from the where-is-an-up-to-date-repository-for-docs dept.

Operating Systems 61

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?"

cancel ×

61 comments

Sorry! There are no comments related to the filter you selected.

Wikis are a poor choice for documentation layout. (3, Insightful)

oyenstikker (536040) | more than 7 years ago | (#18796137)

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.

Re:Wikis are a poor choice for documentation layou (0, Interesting)

Anonymous Coward | more than 7 years ago | (#18796257)

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).

Re:Wikis are a poor choice for documentation layou (1)

oyenstikker (536040) | more than 7 years ago | (#18807801)

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.

Re:Wikis are a poor choice for documentation layou (0)

Anonymous Coward | more than 7 years ago | (#18796295)

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.

Re:Wikis are a poor choice for documentation layou (2, Insightful)

div_2n (525075) | more than 7 years ago | (#18796557)

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.

Re:Wikis are a poor choice for documentation layou (2, Insightful)

Smidge204 (605297) | more than 7 years ago | (#18796625)

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=

Re:Wikis are a poor choice for documentation layou (4, Insightful)

fotbr (855184) | more than 7 years ago | (#18796653)

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).

Re:Wikis are a poor choice for documentation layou (2, Interesting)

mu22le (766735) | more than 7 years ago | (#18797151)

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?


'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.

Re:Wikis are a poor choice for documentation layou (1)

Intron (870560) | more than 7 years ago | (#18800153)

"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 [opensrc.org] is the only place to go to try to find what people have done to get specific cards working or problems solved.

Re:Wikis are a poor choice for documentation layou (1)

BrokenHalo (565198) | more than 7 years ago | (#18802089)

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.

Re:Wikis are a poor choice for documentation layou (1)

fotbr (855184) | more than 7 years ago | (#18804557)

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".

Re:Wikis are a poor choice for documentation layou (2, Informative)

shaitand (626655) | more than 7 years ago | (#18805325)

'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.

Re:Wikis are a poor choice for documentation layou (1)

fotbr (855184) | more than 7 years ago | (#18811115)

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.

Re:Wikis are a poor choice for documentation layou (0)

Anonymous Coward | more than 7 years ago | (#18833561)

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.

Benevolent Dictators Helpful (3, Interesting)

bill_mcgonigle (4333) | more than 7 years ago | (#18797467)

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.

Re:Benevolent Dictators Helpful (2, Informative)

drinkypoo (153816) | more than 7 years ago | (#18798061)

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.

Using drupal's book module you can create hierarchies and restrict users by path.

Users can then create and/or edit pages as appropriate.

The permissions aren't quite granular enough to do all that you want, I don't think, but adding permissions and permission checks is trivial. And I mean that. I am not much of a programmer, so if I say it's trivial, then it's true :)

Re:Benevolent Dictators Helpful (1)

emj (15659) | more than 7 years ago | (#18801123)

Trivial... Reading the permission table in drupal is a job for ten legal experts. Drupal gives admins the possibility to give permission, but it usually just hinder creativity, and in the end it gets you no where.

Re:Benevolent Dictators Helpful (1)

drinkypoo (153816) | more than 7 years ago | (#18801299)

What I'm talking about is adding a permission. It's VERY easy to create a new permission in the system, and it's also trivial to add a check for that permission to the code for any module or the core. You don't need to read the permission table, because drupal does that for you. You just check for a permission and you get either a true or false back. You need an access module if you want to restrict people from doing things (ordinarily.) But you can do permission checks without an access module.

Re:Wikis are a poor choice for documentation layou (1)

GrievousMistake (880829) | more than 7 years ago | (#18803359)

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.

Re:Wikis are a poor choice for documentation layou (0)

Anonymous Coward | more than 7 years ago | (#18810413)

Try http://man-wiki.net/ [man-wiki.net] its pretty good

Research on online documentation (1)

andyo (109338) | more than 7 years ago | (#18811787)

People interested in the quality and use of documentation might be interested in some of my articles on the subject:

TLDP was useful at one time (4, Insightful)

sarathmenon (751376) | more than 7 years ago | (#18796221)

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 [gentoo-wiki.com] 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.

Re:TLDP was useful at one time (4, Insightful)

MankyD (567984) | more than 7 years ago | (#18796361)

I need to second Gentoo-Wiki as a wiki done right. When I need to get something working, 99% of the time, Gentoo-Wiki has me covered. As far as formal documentation is concerned, no, it is not the best perhaps. But as far as useful documentation is concerned, it does a great job.

There are weak spots in some smaller sections that I've found, but it's generally enough to get me started. Furthermore, once I figure out some more details about what I am trying to accomplish, I just update the wiki ;)

Re:TLDP was useful at one time (1)

jimstapleton (999106) | more than 7 years ago | (#18796473)

I agree, on the few times that I can find what I want in the FreeBSD documentation and mailing lists/archives, which is typically for userland problems, the GentooWiki is often where google takes me to find the answer. I have to change a couple of small commands, and device paths sometimes, but I'm familiar with both sides of the fence, so that really isn't a challange.

typo (1)

jimstapleton (999106) | more than 7 years ago | (#18796501)

typo: s/can/can't/

Re:TLDP was useful at one time (1)

porkThreeWays (895269) | more than 7 years ago | (#18796649)

Hearing about TLDP is like a trip down memory lane. I got into Linux in the late 90's and it was pretty thriving back then. While the information I got from there was fantastic, I think we have better quality information available today. Though it's not in any single source, Google is so good at finding relevant information I don't think central information sources are needed as much. There's added benefits of duplicate information as sometimes it's not explained clearly from one source. TLDP was good for its day and is where I got a huge bulk of my Linux education, however I just don't think it's needed anymore.

Agree: Gentoo Wiki is great, even for non-Gentoo (2, Interesting)

KWTm (808824) | more than 7 years ago | (#18802499)

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!

Re:Agree: Gentoo Wiki is great, even for non-Gento (0)

Anonymous Coward | more than 7 years ago | (#18821355)

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.

Google (2, Informative)

gvc (167165) | more than 7 years ago | (#18796253)

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.

Re:Google (2, Informative)

gEvil (beta) (945888) | more than 7 years ago | (#18796327)

Don't forget to check Usenet (or Google Groups for the NNTP-challenged) for answers. After all, this is the sort of thing that it excels at (or did at one time).

Defragmentation? (3, Funny)

tygerstripes (832644) | more than 7 years ago | (#18796373)

As long as you're not using fat32, you shouldn't need to...

*ducks*

Re:Defragmentation? (1)

BobPaul (710574) | more than 7 years ago | (#18802747)

My thought exactly. There's no "fragmentation" in the documentation because it's not appropriate for any of the major file systems

Question: (1, Insightful)

skinfitz (564041) | more than 7 years ago | (#18796393)

WHAT Linux documentation?

Best doc available is on IRC ! (3, Insightful)

Anonymous Coward | more than 7 years ago | (#18796841)

* 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

Re:Best doc available is on IRC ! (1)

twilight30 (84644) | more than 7 years ago | (#18802311)

LOL! Awesome ;)

Re:Best doc available is on IRC ! (1)

joe_n_bloe (244407) | more than 7 years ago | (#18863391)

HTH and HAND

There's a limit... (2, Funny)

DoofusOfDeath (636671) | more than 7 years ago | (#18796923)

Doesn't the documentation automatically get defragged every 30th time you read it?

Fragmented, yes (1)

Vulva R. Thompson, P (1060828) | more than 7 years ago | (#18796979)

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.

Was wondering just the same thing today (1)

TheVoice900 (467327) | more than 7 years ago | (#18797141)

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?

Distro forums aren't very good. (3, Interesting)

Short Circuit (52384) | more than 7 years ago | (#18798021)

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.

Re:Distro forums aren't very good. (2, Interesting)

Anonymous Coward | more than 7 years ago | (#18798201)

It's even worse than that on Ubuntu's forums
advices are utterly inadequate too....
like a dkpg-reconfigure --all
just to reconfigure ONE package that failed....
(and reading at the man of the command won't help you to much either because then you have to know what is the package that accept the reconfiguration since the command returns nothing in numerous cases...)

of course it works.....no it doesn't really help in the long time.
Should I mention how many dummies are just advicing to change edgy to feisty in sourcelist to upgrade to feisty when the official stance is NOT TO DO that....
Ubuntu forums are NOT a good source of information when you have a problem.
They are a good source of information to know that you are not alone struggling with one of their numerous bugs though.

Re:Distro forums aren't very good. (1)

Short Circuit (52384) | more than 7 years ago | (#18798339)

I just wish Ubuntu forums wasn't the top entry in any google search for my issues.

Re:Distro forums aren't very good. (0)

Anonymous Coward | more than 7 years ago | (#18805687)

Forums are a bunch of socialites helping each other.

Check out the real help pages. help.ubuntu.com (and the community section of that).

Re:Distro forums aren't very good. (1)

dylan_- (1661) | more than 6 years ago | (#18841727)

It bears mentioning again: The questions were worded well, with important details provided.
No, they were poorly written, with no details of any worth, and despite this they were answer helpfully and completely.

Hey, since we're not providing any links, we can just make up any old crap, yes? Oops! Did I just give away your secret posting technique? Sorry...

Re:Distro forums aren't very good. (1)

Short Circuit (52384) | more than 6 years ago | (#18842951)

Next time I run into a similar issue, I'll send you some.

Wait...not providing contact information? So we can say any old thing online without accountability, right? A four-digit UID is the only thing separating you from Anonymous Cowards. Well, that, and I've seen better comments posted as AC.

As one example, I encountered a bizarre issue with the NVIDIA driver that responded in some sort of object allocation error. A google for the error came back with an Ubuntu forum post complete with a description of the error and some X logs. But not one reply.

None of the other search results gave better answers, and I wound up giving up trying to get the NVidia driver working on that system. (Which didn't bother me. It wasn't my system, and the guy who wanted 3D acceleration refused to understand that it wasn't necessary for the software-rendered Windows game he was already running under WINE.)

Re:Distro forums aren't very good. (1)

dylan_- (1661) | more than 7 years ago | (#18852147)

"Contact information"? What are you talking about?

Since you're having trouble understanding me, let me put it more clearly. I constantly hear these whines about poor support on forums, yet the whiner (in this case, you) never provides a link to the thread illustrating his point. And when I go to the Ubuntu forums what I see is useful advice being given to help people solve their problems. You'd think if there were so many threads where no help was given, you'd manage to link to at least one or two, no?

I think you just make this crap up, frankly. And you've done it again with your Nvidia error post. Maybe that is a true story, but I seriously doubt it since you can't even get it straight in your own post (how was it that he "refused to understand" something, when he never had any replies?)

Do you get some weird pleasure from denigrating the work of volunteers, or are you just generally a miserable sod?

Re:Distro forums aren't very good. (1)

Short Circuit (52384) | more than 7 years ago | (#18853029)

"Contact information"? What are you talking about?
A means of sending you a link after this /. article expires.

Since you're having trouble understanding me, let me put it more clearly. I constantly hear these whines about poor support on forums, yet the whiner (in this case, you) never provides a link to the thread illustrating his point. And when I go to the Ubuntu forums what I see is useful advice being given to help people solve their problems. You'd think if there were so many threads where no help was given, you'd manage to link to at least one or two, no?
I don't go directly to Ubuntu forums, I google for the problem. For better or for worse, the Ubuntu forums' site's pagerank puts it at or near the top of the search results every time.

I think you just make this crap up, frankly. And you've done it again with your Nvidia error post. Maybe that is a true story, but I seriously doubt it since you can't even get it straight in your own post (how was it that he "refused to understand" something, when he never had any replies?)
You seriously need to see someone about your paranoia. In addition, you should pay attention to the context of statements. I mentioned two people in my post: Some poor sap who posted to the forum without receiving a reply, and my roommate for whom I was trying to fix the same problem. My roommate was the guy who "refused to understand" that he didn't need 3D acceleration for what he wanted to use his computer for.

Do you get some weird pleasure from denigrating the work of volunteers, or are you just generally a miserable sod?
No, and no. Try doing a Google Groups search for my email address...I've spent a great deal of my time contributing to Linux newsgroups and LUG mailing lists, when I've had time to spare from classes.

Re:Distro forums aren't very good. (1)

dylan_- (1661) | more than 7 years ago | (#18854123)

No paranoia here. You make a claim that flies in the face of common experience, and you don't bother providing a link to back it up when it should be trivial to do so. The simplest explanation for that is that you're lying. Still, since you say you do contribute to newsgroups etc, I'll assume you weren't lying, so mea culpa.

I still think you're out of line with criticising the Ubuntu forums though. No doubt there are *some* problems they can't fix, but it's certainly not the general case. If you don't want the forums in your results use "-ubuntu" in your google search.

Re:Distro forums aren't very good. (1)

Short Circuit (52384) | more than 7 years ago | (#18855569)

You make a claim that flies in the face of common experience
Maybe for others with simple problems. My experience probably mirrors other power users'.

and you don't bother providing a link to back it up when it should be trivial to do so.
Finding a specific forum post when one doesn't even remember the exact keywords used to find it is no mean feat, especially for a forum site as large as Ubuntu's. What do you want? Idetic memory?

I still think you're out of line with criticising the Ubuntu forums though. No doubt there are *some* problems they can't fix, but it's certainly not the general case.
Quite possibly true. My original post was from the perspective of a power user, but I didn't make that sufficiently clear.

In my experience, the "general case" consists of ten or fifteen problems which are encountered multiple times. Anything else either begets a "file a bug report" response, or gets ignored.

If you don't want the forums in your results use "-ubuntu" in your google search.
Not helpful when I'm looking for a solution for my Ubuntu box. Generic searches often yield tutorials for Fedora and Mandriva, not Ubuntu. But point taken.

You know what's really rediculous, from my perspective? I tried to find a link to one particular forum thread where everyone recommended ClarkConnect over Ubuntu when someone asked about setting up a gateway. Instead, I found two posts that were exactly what I was looking for in the first place. I don't know if the pagerank changed or if my search keywords changed. By the datestamps, they're certainly not new posts.

*sigh*

News to me... (3, Insightful)

Guspaz (556486) | more than 7 years ago | (#18799013)

You mean, Linux has documentation that isn't a man page or a '-h' switch?!

Re:News to me... (0)

Anonymous Coward | more than 7 years ago | (#18800223)

Yeah. Get the source tarball and read the comments in the code you lazy SOB.

Re:News to me... (1)

laejoh (648921) | more than 7 years ago | (#18853899)

d00d! u R an 31337 hax0r

99.99% of the time I use only one resource. (1)

shaitand (626655) | more than 7 years ago | (#18805417)

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 doc fragmentation predates TLDP (1)

darkuncle (4925) | more than 7 years ago | (#18805731)

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 [openbsd.org] 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 ...)

Re:Linux doc fragmentation predates TLDP (1)

WgT2 (591074) | more than 7 years ago | (#18810677)

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.

I think you're absolutely right: the development model difference between Linux and the BSD's (apart from the fact that there are different distros thereof) is that of unity -- Linux only has the kernel under control of a central unit (Linus) -- FreeBSD, and I would guess OpenBSD as well, has a complete operating system under a centralized control unit. Distros fill this roll in FreeBSD. It works but it is less than ideal in that it is subject to much flux.

That being said, I've read before that Linux has likely been more successful because of this very lack of 'complete OS' status in that the kernel is essentially under the control/direction of one person. (That AT&T lawsuit might have been a growth-stunter as well, but perhaps we'll never know.)

All I know is, though, is that once I switched to FreeBSD I got a lot more confidence in my OS than I ever had with Linux: Linux never feels complete to me, like it's a work in progress, unsettled, and shaky. If you have felt that way about your OS of choice, you should likely switch to something else, as I did. I still use Linux, Debian Etch, but only at work for the sake of running VMWare 5.5. I also won't go around condeming or badmouthing it, I still like what it does and often stands for; it certainly is much funny to work with than Windows ever will be... unless they switch their kernel like Mac did. It then MIGHT be fun, but I doubt it.

Now, if only Adobe would bring Flash to FreeBSD...

P.S. Thanks for the reminder in the sig.

Re:Linux doc fragmentation predates TLDP (1)

darkuncle (4925) | more than 7 years ago | (#18811547)

agreed - Linux is not "bad" or "wrong" or to be avoided because of the holes in the docs, it's just one of Linux's flaws. Every OS has them - pick which ones you are most able to live with for the project at hand. Generally the documentation flaw is a relatively minor one for enterprise apps, which is why we run so much Linux @work - but commercial support doesn't really mean much to me personally (consistent man pages are more valuable), which is why I run OpenBSD for my colo stuff and @home.

I think you may be the first person to have understood the sig (at least the first to say so :)).

cheers!

Re:Linux doc fragmentation predates TLDP (1)

WgT2 (591074) | more than 7 years ago | (#18827643)

I was just thinking earlier today about if Linux distros don't do a good job of quality control then the BSD's might become more main stream. For example: I was recently using Kubuntu, I did a basic package update, and all of the sudden my X(org) config becaume useless. I think the distros are going to have to be extremely good at delivering consistancy to avoid such simple changes causing such drastic changes.

I did find out that I could get Flash running by installing the flashplugin9 port with the linux-firefox port. I had previousyl tried it with the flashplugin7 but without success. While the sound seems to get a little behind the picture, it's good enough for what I want to do with it.

About the sig: I have a confession: Google.com

Old Saw (0)

Anonymous Coward | more than 7 years ago | (#18807689)

"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.

google? (1)

MMC Monster (602931) | more than 7 years ago | (#18807761)

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.

Re:google? (1)

LaurensVH (1079801) | more than 7 years ago | (#18884183)

I have to agree. I use a search engine, especially when I have a specific message that describes my error/problem/amazement. Ususally I feel pretty lucky and find the result instantly.
Check for New Comments
Slashdot Login

Need an Account?

Forgot your password?

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>