Slashdot videos: Now with more Slashdot!

View

Discuss

Share

We've improved Slashdot's video section; now you can view our video interviews, product close-ups and site visits with all the usual Slashdot options to comment, share, etc. No more walled garden! It's a work in progress -- we hope you'll check it out (Learn more about the recent updates).

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

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 late

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

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 fo

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

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.

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

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.

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,

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.

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

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.

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.

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 o

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.

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

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.

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 i

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,

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

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 a

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.

It's even worse than that on Ubuntu's forumsadvices are utterly inadequate too....like a dkpg-reconfigure --alljust 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 so

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

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

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 t

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

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,

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 cent

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 ma

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 lin