Forgot your password?
typodupeerror
Open Source Programming Linux

Is Linux Documentation Lacking? 769

Posted by CmdrTaco
from the hackers-and-english-don't-always-mix dept.
eldavojohn writes "A number of blog posts are surfacing that are calling out the helpful open source community on their documentation. No, not the documentation for the highly skilled technical people, but the documentation from beginner to apprentice. A two-part series by Carla Schroeder lists bad documentation as 'Linux Bug #1' and advises users to use Google as the documentation. We've discussed before some of open source's documentation being out of date. Is it really as bad as these blogs paint it? Has it come down to using Google before a man page?"
This discussion has been archived. No new comments can be posted.

Is Linux Documentation Lacking?

Comments Filter:
  • Re:Of course it is. (Score:3, Informative)

    by ls671 (1122017) * on Thursday December 03, 2009 @11:25AM (#30310544) Homepage

    > Of course it is.

    Agreed, first tip for the "beginner to apprentice":

    Learning to use the "man" command is important, remember that you sometime have to add a number parameter to get the documentation that you want to get ;-)

  • by mark0 (750639) on Thursday December 03, 2009 @11:28AM (#30310594)
    I have found the Ubuntu Community Documentation [ubuntu.com] to be pretty good for cookbook procedures. Their forums pick up the slack for acute issues.
  • by TrisexualPuppy (976893) on Thursday December 03, 2009 @11:29AM (#30310614)
    I don't [tldp.org] think so.
  • by L4t3r4lu5 (1216702) on Thursday December 03, 2009 @11:34AM (#30310670)
    Wireless Howto [tldp.org]

    Wireless Howto
    Roberto Arcomano berto@fatamorgana.com
    v1.6 - July 31, 2002
  • by CasaDelGato (701438) on Thursday December 03, 2009 @11:36AM (#30310698) Homepage
    The whole Linux Mindset to documentation can be summed up in the phrase "use the man page". Yeah, right. Man pages are only semi-useful if you ALREADY KNOW WHAT COMMAND YOU NEED. Trying to FIND the command to do something is nearly impossible. Almost as bad as trying to find out how to configure something. (just edit the twiddly.da config file in the googly.plex directory, note that the syntax is completely different from every other config file on the system.)
  • Re:Yes. (Score:4, Informative)

    by eldavojohn (898314) * <eldavojohnNO@SPAMgmail.com> on Thursday December 03, 2009 @11:37AM (#30310704) Journal

    Writing documentation is hard work and is boring. It is also thankless.

    Amen. But, believe it or not there are people out there looking to assist open source by doing tech/doc writing [slashdot.org] for it. The comments in that thread have some really good resources if anyone out there is in total despair or is curious how they can help out open source documentation. I probably should have linked to that in the summary but my submissions have been way too link heavy lately.

  • by Bluesman (104513) on Thursday December 03, 2009 @11:38AM (#30310722) Homepage

    >apropos [thing I want]

    But Linux distros could learn a lesson from FreeBSD in this regard. The FreeBSD docs are nothing short of excellent, and standard for the entire system.

  • Re:Of course it is. (Score:5, Informative)

    by Penguinisto (415985) on Thursday December 03, 2009 @11:41AM (#30310778) Journal

    True - though something is lacking in TFA: there is a diff between hitting the docs for learning, and hitting them for troubleshooting.

    The man pages are more for learning (you can troubleshoot with them too, but diagnostic info in them are going to be lacking, just like trying to rely on the Windows Help files to fix a busted Exchange connector). Odds are, a beginner/apprentice won't know what to do with 'em for fixing a problem unless he/she is a royal badass at general computing/programming practices.

    For troubleshooting, you're gonna have to hit Google - you have better odds there that someone else had the same problem and posted it (and its solution). There was once a time when you could write up docs for troubleshooting and diagnostics, covering up to 80% or more of what most folks run up against.

    It still boils down to upping your skills on the OS and on general practices, though.

  • by godrik (1287354) on Thursday December 03, 2009 @11:42AM (#30310798)

    Well, the man pages are only supposed to give the formal parameters of the command. The actual use of the command in a given context are given by HOW TOs.

  • Re:Of course it is. (Score:2, Informative)

    by d3m0nCr4t (869332) on Thursday December 03, 2009 @11:52AM (#30310948)
    Try "apropos"!
  • Huh? (Score:3, Informative)

    by BenEnglishAtHome (449670) on Thursday December 03, 2009 @12:01PM (#30311122)

    Somebody modded this insightful? WTF?

  • Re:Well, No Shit (Score:3, Informative)

    by bsDaemon (87307) on Thursday December 03, 2009 @12:09PM (#30311262)
    If you use a long-form BSD license (with the credit clause), then they can't take the all the credit -- they have to indicate that they borrowed your source as a starting point.

    I don't do much coding, so I don't release a lot of code beyond some Perl or Shell stuff, but when I do, I prefer BSD licensing to GPL licensing. Maybe I just don't think my code is novel enough for anyone to want to hijack anyway.
  • Re:Ok then.. (Score:3, Informative)

    by jimicus (737525) on Thursday December 03, 2009 @12:22PM (#30311484)

    I'd insert a blank CD in the CD ROM drive.

    Windows would then automatically pop up a dialog asking me what I want to do with this blank CD - such as write files to it.

  • Re:Of course it is. (Score:3, Informative)

    by mweather (1089505) on Thursday December 03, 2009 @01:29PM (#30312796)
    man apt-cache. That'll tell you how to search the repo for a CD burning program.
  • by Anonymous Coward on Thursday December 03, 2009 @01:30PM (#30312814)

    I completely agree. I use Linux about 99% of the time, but recently test drove FreeBSD. I was amazed that the man pages and FreeBSD HandBook actually had useful things in them! It was like expecting to find a spray painted wall and instead discovering Oscar Wilde.

  • by ThePhilips (752041) on Thursday December 03, 2009 @01:32PM (#30312842) Homepage Journal

    GNU info needs to just die

    +1

    The shell function makes "info" tad bit more usable to me:

    info() { /usr/bin/info --subnodes --output=- "$@" | $PAGER; }

  • by Anonymous Coward on Thursday December 03, 2009 @02:35PM (#30313922)

    Type apropos. It will show you what commands do a specified task.

    apropos burn
    gnomebaker (1) - an easy to use CD/DVD burner for GNOME

  • by SanityInAnarchy (655584) <ninja@slaphack.com> on Thursday December 03, 2009 @04:28PM (#30315562) Journal

    I'd argue that sending the uncompressed file is faster, because you don't need to waste half an hour writing an elaborate program.

    Try 2-5 minutes. And it's then reusable. By now, I know that sequence of commands well enough I could probably do it in 30 seconds to a minute.

    And it is actually meaningful here. The sooner I can get that image taken, the sooner I can wipe the drive, and the sooner I can get the machine back in the hands of the customer -- or myself, for that matter. The server can then sit there crunching for days, if I want -- and lrzip will take days.

    AND it's non-user friendly.

    Yes, it is. It's a non-user-friendly way of doing something for which a user-friendly way doesn't exist, anywhere, that I know of. That's the point -- again, if there's a GUI that'll do the same job, that is better for the average user. But having a commandline available is better than nothing at all.

    And again, you need the commandline version anyway. Another example -- suppose I'm responsible for maintaining a large network, so I need to be able to do things like this automatically. That is, walk up to a machine, have it boot from the network (or from a CD), into a system which automatically sends an image to the backup server, then wipes it with a clean image -- then the backup server can have a cron job to flush old images after a week or so, when we're reasonably sure the user doesn't need any files from them.

    Now, how would I build a scheme like that from a GUI? You could argue that it'd be nice to have a GUI tool to configure the netboot server, or build a CD image for me, but ultimately, such a tool is easier to write if it can just add a few commands to a boot script -- and even if such a tool doesn't exist, a half hour of my time to build that system once will pay for itself many times over, when multiplied over a network.

    Replacing the CLI with a mouse improves usability.

    It improves discoverability, hands-down. That's what commandlines suck at. This is a good point, right here:

    without memorizing the commands or digging through a manual.

    But that is not about usability, it's about discoverability and learning curve, which is only part of usability. For example: I already know how to navigate my filesystem with the commandline, move files around, etc -- it took me longer to learn to do this, and things like 'cd' and 'ls' aren't right there in my face to find, I had to read some tutorials, etc. Tab-completion isn't obvious, either -- these are all things I had to be taught in some way or other.

    The result is, I'm faster with the commandline than I am with the mouse. Really. Using cd and ls, with tab-completion, is faster than pointing and clicking on icons of folders. And once I've navigated to where my iso is, typing 'wodim foo.iso' is much faster than right-clicking on the image, looking for an option to burn, and clicking through a wizard.

    And that's without even considering scripts. Taking the above example, I usually do something like 'wodim -dao -eject foo.iso' -- if this ever got annoying to type, I could easily make a new, shorter command which would do just that.

    Now, that's not universally true. I've used lynx, and I wish I had better keyboard control in my browser, but a web browser is still much better in a GUI. I certainly wouldn't argue that photo editing or 3D modeling would be better done with a commandline. Each has its usefulness.

    I also agree that if you're trying to do something simple, you shouldn't need a commandline. And this is mostly true on a modern Linux. Plug in your digital camera, and the appropriate software pops up -- that's even easier than on Windows, which makes you wait while it installs drivers, last I checked.

    But to say that any need for the commandline is an indication of something broken is demonstrably wrong.

"Atomic batteries to power, turbines to speed." -- Robin, The Boy Wonder

Working...