Is Linux Documentation Lacking?

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

yes yes

[Anonymous Coward]

I google for man pages.

Re:Documentation is very lacking

[nomadic]

Well I've been using Linux since 1979, and the documentation has never been that great. I remember asking Linus and some of the other developers about it when I ran into them at Studio 54, but they were too stoned to answer. Man, it was crazy back then, you'd get high and write a program and you wouldn't even care about the documentation. You'd just copy over someone else's man pages, or paste in Beegees lyrics, or whatever you're drug-addled brain came up with at the time.

Re:The Culture needs a slight change.

[godrik]

It also saves programmers the time of having to answer needless questions.

Don't worry! I have scripts to answer RTFM to whole forums at once. I do not even have to read the post. Just to be undetected sometimes the scritps replies "Read the source Luke" instead.

Re:Of course it is.

[prgrmr]

man microwave

Re:Documentation is very lacking

[Goaway]

> apropos burn a cd

drutil(1) - interact with CD/DVD burners
hdiutil(1) - manipulate disk images (attach, verify, burn, etc)
CONF_modules_free(3ssl), CONF_modules_finish(3ssl), CONF_modules_unload(3ssl) - OpenSSL configuration cleanup functions
CONF_modules_load_file(3ssl), CONF_modules_load(3ssl) - OpenSSL configuration functions
APR(3pm) - Perl Interface for Apache Portable Runtime (libapr and libaprutil Libraries)
APR::Base64(3pm) - Perl API for APR base64 encoding/decoding functionality
APR::Brigade(3pm) - Perl API for manipulating APR Bucket Brigades
APR::Bucket(3pm) - Perl API for manipulating APR Buckets
APR::BucketAlloc(3pm) - Perl API for Bucket Allocation
APR::BucketType(3pm) - Perl API for APR bucket types
APR::Const(3pm) - Perl Interface for APR Constants
APR::Date(3pm) - Perl API for APR date manipulating functions
APR::Error(3pm) - Perl API for APR/Apache/mod_perl exceptions
APR::Finfo(3pm) - Perl API for APR fileinfo structure
APR::IpSubnet(3pm) - Perl API for accessing APRs ip_subnet structures
APR::OS(3pm) - Perl API for Platform-specific APR API
APR::PerlIO(3pm) - -- Perl IO layer for APR
APR::Pool(3pm) - Perl API for APR pools
APR::SockAddr(3pm) - Perl API for APR socket address structure
APR::Socket(3pm) - Perl API for APR sockets
APR::Status(3pm) - Perl Interface to the APR_STATUS_IS_* macros
APR::String(3pm) - Perl API for manipulating APR UUIDs
APR::Table(3pm) - Perl API for manipulating APR opaque string-content tables
APR::ThreadMutex(3pm) - Perl API for APR thread mutexes
APR::ThreadRWLock(3pm) - Perl API for APR thread read/write locks
APR::URI(3pm) - Perl API for URI manipulations
APR::UUID(3pm) - Perl API for manipulating APR UUIDs
APR::Util(3pm) - Perl API for Various APR Utilities
ASN1_OBJECT_new(3ssl), ASN1_OBJECT_free(3ssl) - object allocation functions
ASN1_STRING_dup(3ssl), ASN1_STRING_cmp(3ssl), ASN1_STRING_set(3ssl), ASN1_STRING_length(3ssl), ASN1_STRING_length_set(3ssl), ASN1_STRING_type(3ssl), ASN1_STRING_data(3ssl) - ASN1_STRING utility functions
ASN1_STRING_new(3ssl), ASN1_STRING_type_new(3ssl), ASN1_STRING_free(3ssl) - ASN1_STRING allocation functions
ASN1_STRING_print_ex(3ssl), ASN1_STRING_print_ex_fp(3ssl) - ASN1_STRING output routines
ASN1_generate_nconf(3ssl), ASN1_generate_v3(3ssl) - ASN1 generation functions
Algorithm::Annotate(3pm) - represent a series of changes in annotate form
Algorithm::Diff(3pm) - Compute `intelligent' differences between two files / lists
Algorithm::DiffOld(3pm) - Compute `intelligent' differences between two files / lists but use the old (<=0.59) interface
Alien::wxWidgets(3pm) - building, finding and using wxWidgets binaries
Alien::wxWidgets::Utility(3pm) - INTERNAL: do not use
AnyDBM_File(3pm) - provide framework for multiple DBMs NDBM_File, DB_File, GDBM_File, SDBM_File, ODBM_File - various DBM implementations
Apache2::Access(3pm) - A Perl API for Apache request object: Access, Authentication and Authorization
Apache2::Build(3pm) -

RTFM

[thijsh]

Yeah, but don't even try to ask for any help, you'll most likely get an RTFM response. XKCD said it best: http://xkcd.com/293/ [xkcd.com]

I think it's safe to say the documentation isn't really lacking, but the support is... :)

Comment removed

[account_deleted]

Comment removed based on user account deletion

Re:Of course it is.

[ls671]

man 1 cdrdao

Re:Of course it is.

[Anonymous Coward]

$ man microwave No manual entry for microwave You tricked me!

Re:Of course it is.

[ls671]

> You've lost me already. I'm having to look up what "man" does.

try:
man man

Re:Documentation is very lacking

[BrentH]

I've been using Windows since 1954, and I've never needed a manual to open them!

Re:Of course it is.

[Anonymous Coward]

Well, what is he doing in the kitchen anyway? That is the job of the woman.

Re:Of course it is.

[ais523]

$ man -k burn cd
brasero (1) - Simple and easy to use CD/DVD burning application for ...
k3b (1) - KDE CD burning program

There were more answers than those two, but either of the first two looks a sensible choice for burning CDs. (The results quickly drop off in quality, though; the fourth was the Perl module Language::INTERCAL::Charset::EBCDIC, which I strongly hope can't burn CDs...)

Re:Huh?

[gzipped_tar]

I've been posting on Slashdot since World War II, and the silly trolls have always been modded +5 Insightful ;)

Re:Of course it is.

[gr8_phk]

I just put in a blank CD. Then a folder appears on the desktop with a button to burn the CD. I drag the file I want into there and hit that button. I'm not sure what this MAN thing is everyone keeps talking about.

Re:Of course it is.

[ciderVisor]

Welcome to Slashdot !

Re:Of course it is.

[Anonymous Coward]

Worse, it's responses like the GP's that compounds the problem.

Noob: I don't know how to use Linux! Won't someone help me?
BOFH: *grumble*grumble* Look, here's the "man" command, dumbass. It obviously means "MANual". Get it? Figured you looked too stupid to figure out how to use Linux...
Noob: Um... when I type that, all I get is "What manual page do you want?" How do-
BOFH: Why you rotten little... just how stupid ARE you? Were you born and raised with Windows or something? You type in the command, kernel function, or standard library call in after "man", just like we've done for the past TWENTY FUCKING YEARS OF UNIX. Hello? Have you been paying ANY attention at all, you worthless little Windows runt? If I hear you badmouthing one of the most hallowed and revered of Unix commands again, I'll-
Noob: So... er... what man command do I use to learn how to burn a CD?
BOFH: (eyes starting to turn red, veins now starting to pop out of head, teeth clenching almost to the point of shattering them by the pressure) You... were... asking... about... MANPAGES... YOU... STUPID... ASSHOLE! What the fuck is WRONG with you? You don't use man to burn a CD! Where the hell were you raised? In Redmond? I bet you don't even know what revision of the CD filesystem to use to optimize storage and retain symlinks! As everyone ALREADY KNOWS, ASSHAT, you have to build up an ISO image from on-filesystem objects using the proper options for your image of choice, make sure the appropriate kernel options are compiled in (or, of course, make and install the proper modules via modprobe or insmod, or via the autoloading mechanism which ONLY the uneducated scum use because they don't know the glories of "pure" Linux from ten or so years ago, the stupid "modern" bastards), THEN you can "burn a CD", as you so quaintly put it! WHAT PART OF THIS IS NOT OBVIOUS TO YOU?!?
Noob: I...
BOFH: (starting to shake from pure rage) You're clearly too much of a moron to truly enjoy Linux! GET OUT! GET OUT OF MY SIGHT, WINDOWS USER! OUT! AND TAKE YOUR GODDAMNED "PRETTY" GUI WITH YOU!
Noob: Hey, guess what? In the time it took you to rant about all that, I got my CD burned under Windows and didn't have a raving insular lunatic insult me. And I was able to do it without having to study the history of an operating system. Sounds like I'm using Windows from now on.
BOFH: *sniff* Why don't people like Linux? We're so superior!

Re:Of course it is.

[Yvan256]

woman microwave

Re:Of course it is.

[machine321]

Can't emacs do it?

Re:Of course it is.

[Anonymous Coward]

I'm not sure what this MAN thing is everyone keeps talking about.

That's because MAN doesn't actually exist.

Re:Of course it is.

[ClosedSource]

Believe it or not Wikipedia isn't the ultimate source of information.