Follow Slashdot blog updates by subscribing to our blog RSS feed

 



Forgot your password?
typodupeerror
×
Operating Systems Software

Fragmentation in Linux Documentation? 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?"
This discussion has been archived. No new comments can be posted.

Fragmentation in Linux Documentation?

Comments Filter:
  • 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.
    • 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
    • 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
    • by fotbr ( 855184 ) on Thursday April 19, 2007 @09:17AM (#18796653) Journal
      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: (Score:2, Interesting)

        by mu22le ( 766735 )

        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.
      • by Intron ( 870560 )
        "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.
        • by fotbr ( 855184 )
          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,
          • Re: (Score:3, Informative)

            by shaitand ( 626655 )
            '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.

            • by fotbr ( 855184 )
              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.
    • by bill_mcgonigle ( 4333 ) * on Thursday April 19, 2007 @10:15AM (#18797467) Homepage Journal
      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: (Score:3, Informative)

        by drinkypoo ( 153816 )

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

        • by emj ( 15659 )
          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.
      • That would be Zwiki. Eg: http://zwiki.org/FrontPage/contents#PageHierarchy [zwiki.org]. This was partly influenced by Drupal's books.
    • 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
    • People interested in the quality and use of documentation might be interested in some of my articles on the subject:
  • 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.
    • by MankyD ( 567984 ) on Thursday April 19, 2007 @08:53AM (#18796361) Homepage

      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,
  • Google (Score:3, Informative)

    by gvc ( 167165 ) on Thursday April 19, 2007 @08:44AM (#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: (Score:3, Informative)

      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).
  • by tygerstripes ( 832644 ) on Thursday April 19, 2007 @08:54AM (#18796373)
    As long as you're not using fat32, you shouldn't need to...

    *ducks*

    • by BobPaul ( 710574 ) *
      My thought exactly. There's no "fragmentation" in the documentation because it's not appropriate for any of the major file systems
  • Question: (Score:2, Insightful)

    by skinfitz ( 564041 )
    WHAT Linux documentation?
  • by Anonymous Coward on Thursday April 19, 2007 @09:31AM (#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
  • by DoofusOfDeath ( 636671 ) on Thursday April 19, 2007 @09:37AM (#18796923)
    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
  • 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
  • by Short Circuit ( 52384 ) * <mikemol@gmail.com> on Thursday April 19, 2007 @10:48AM (#18798021) Homepage Journal
    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: (Score:2, Interesting)

      by Anonymous Coward
      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 so
    • by dylan_- ( 1661 )

      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...
      • 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
        • by dylan_- ( 1661 )
          "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 t
          • "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 t

            • by dylan_- ( 1661 )
              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
              • 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 multi

  • News to me... (Score:4, Insightful)

    by Guspaz ( 556486 ) on Thursday April 19, 2007 @11:46AM (#18799013)
    You mean, Linux has documentation that isn't a man page or a '-h' switch?!
  • 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,
    • by WgT2 ( 591074 )

      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

      • by darkuncle ( 4925 )
        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
        • by WgT2 ( 591074 )

          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

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

Life is a healthy respect for mother nature laced with greed.

Working...