×

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!

Is Linux Documentation Lacking?

CmdrTaco posted more than 4 years ago | from the hackers-and-english-don't-always-mix dept.

Open Source 769

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

cancel ×
This is a preview of your comment

No Comment Title Entered

Anonymous Coward 1 minute ago

No Comment Entered

769 comments

Of course it is. (4, Interesting)

Mongoose Disciple (722373) | more than 4 years ago | (#30310474)

But on the flipside, I tend to use Google as the documentation for Windows/MacOS and most assorted non-free software that runs on them, too.

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

ls671 (1122017) | more than 4 years ago | (#30310544)

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

Re:Of course it is. (1)

WormholeFiend (674934) | more than 4 years ago | (#30310724)

I've been using linux for just over a year now and I didn't know about "man".

I get by with googling when I have an issue with something.

Most often, the issue is a program I would love to try, but that I can't figure out how to set up, or even run properly if I manage to set it up.

The big apps are user-friendly and intuitive enough that most computer literate people could switch to linux, but smaller apps could use some development in that area.

IMHO.

Re:Of course it is. (1, Flamebait)

Cimexus (1355033) | more than 4 years ago | (#30310836)

The first time I tried linux, I already knew about man (from Slashdot posts, no less).

Well man just confused me more than anything else. Unreadable and full of jargon. Linux, I feel, does need some form of guide for newbies. I'm not afraid of the command line, but just listing out a whole bunch of switches with some description of what they do that itself doesn't actually mean anything to me, isn't enough.

Google reveals a lot of very helpful and well-written newbie guides though. Perhaps the best of those should be adapted and built-in to the documentation shipping with new distros?

Re:Of course it is. (1)

L4t3r4lu5 (1216702) | more than 4 years ago | (#30310908)

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

This is the problem with documentation. I have no idea what "man" "grep" or "ls" do. If you tell me that "man" is "help", "grep" is a word search function, and "ls" is like "dir" then I'm fine. But that's not there.

Re:Of course it is. (4, Informative)

Penguinisto (415985) | more than 4 years ago | (#30310778)

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.

Yes it is terrible! (5, Insightful)

InsaneProcessor (869563) | more than 4 years ago | (#30310480)

This is one of the key reasons Linux is not mainstream for users (not us geeks but real users). The user does not want to learn how to do anything more on his computer than get is work done or enjoy the entertainment. User level documentation simple does not exist.

Re:Yes it is terrible! (1, Interesting)

Anonymous Coward | more than 4 years ago | (#30310532)

I haven't seen any difference with windows systems. On mac at least you have the initial link to the online tutorials.

Re:Yes it is terrible! (4, Insightful)

Americium (1343605) | more than 4 years ago | (#30310672)

Exactly. Creating documentation for mainstream users is completely pointless. I personally think Ubuntuforums has great docs. I can just copy paste what they tell me, and voila, i have fakeraid setup, or whatever else is hard to install.

Re:Yes it is terrible! (5, Insightful)

FTWinston (1332785) | more than 4 years ago | (#30310762)

I had several issues and tasks that I wished to perform on an ubuntu install on my now-deceased old machine.

Some were easy to find, but some involved wading through page after page of contradictory forum advice, or advice that seemed to completely disable my network adaptor. Things that I had expected to be possible through a GUI required pasting invalid forum syntax into system-critical files, sometimes with unpleasant results.

I was using linux only because I had to (producing dedicated server binaries for a source mod server), and my task was pretty non-trivial for a first-time user. I really did try to enjoy the experience... but I found it largely cumbersome, and haven't been back. Which is a shame, tbh, cos I'd like to like it.

The main problem, for me, was that it felt like for every task I wanted to perform, I had to find an expert person on a forum who already knew precisely how to achieve said task. There was usually little possibility of the self-discovery that is generally possible with an intuitive GUI, in the areas where a GUI was lacking.

With hindsight, it would have been more efficient to have just paid an expert to produce the binary for me. Or better yet, to set up my environment the way I wanted it.

Re:Yes it is terrible! (2, Insightful)

mark-t (151149) | more than 4 years ago | (#30310780)

Nope. Most users don't bother to even *READ* documentation, so the lack of it would not be a factor.

Re:Yes it is terrible! (1)

al3 (1285708) | more than 4 years ago | (#30310812)

The intersection of OSS developers and good technical writers is a small part of the Venn diagram. Nothing would ever be released if a project wasn't considered done until documentation was complete and well written. The strength of OSS is that each person can contribute the part they're good at. If someone makes a good piece of software, it'd be great if someone else came along to document it, and everybody wins.

Re:Yes it is terrible! (2, Insightful)

smooth wombat (796938) | more than 4 years ago | (#30310910)

If someone makes a good piece of software, it'd be great if someone else came along to document it, and everybody wins.

Here's an idea: how about the person who did the actual work do the documentation? That way, since they know all the ins and outs, someone else doesn't have to pester them to find out how to do something and document it.

Yeah, yeah. That would be too easy and make sense. Let someone else take care of the problem because I'm too lazy.

There is no reason in this day and age that the person/people creating these apps can't provide documentation at the same time. As others have already pointed out, until there is good documentation and yes, even a simple walk-through if it's warranted, it will NEVER be the year of Linux on the desktop.

Re:Yes it is terrible! (0)

Anonymous Coward | more than 4 years ago | (#30310816)

I'd say that Linux documentation is bad/lacking even for advanced users and übergeeks.

Re:Yes it is terrible! (1)

djrosen (265939) | more than 4 years ago | (#30310888)

Except the user didn't get that knowledge in Windows by osmosis OR documentation, they had to learn somehow. You think a green user could work there way through photoshop with just the help file and never having to google? Linux isnt mainstream because it doesn't have a multi-billion dollar company marketing for it, that is the ONLY reason.

Re:Yes it is terrible! (2, Insightful)

jellomizer (103300) | more than 4 years ago | (#30310906)

You make it sound like a bad thing...

Yes people don't want to tweak config files to give it an extra 10% speed improvement. Or fuss around searching for "Pure" GNU drivers that work. They just want a system that boots up, allows them to go to their apps get their work done. When they are done with work they may want some entertainment out of the device.

Do you feel you have to know how every component in your car works.
All the technology and people who go is to flushing your toilet making sure that nasty stuff leaving your body doesn't come back to haunt you again.
Do you need to know what materials your desk is made out of, how they cut the wood etc...

There is a lot of stuff going on outside of our areas of interests. We use a lot of such products and services but don't even think about all the details that goes on, for the most part we don't care, even if it vitally important to us, but as long as it works we are happy.

Re:Yes it is terrible! (2, Interesting)

Moryath (553296) | more than 4 years ago | (#30310936)

My experiences (plural) with Ubuntu, MythTV, and MythBuntu (which was supposed to "streamline" the whole process) were similar in trying to set up a DVR.

Consumer-level HDTV card (ATi HDTV Wonder, PCI). ATi video board. ATi Remote Wonder II for my remote control.

Every time a new version of Ubuntu/MythTV/Mythbuntu would come out, I'd try to load it up and get it to work correctly. Multiple people insisting it would work fine, others insisting "no support" for the stuff. Back and forth. Most of the problem stems from the fact that in every stinking version, something gets changed, then it takes them a year or more to document the crap.

In the Ubuntu Hardy Heron attempt, every bit of documentation was either Gutsy Gibbon or Feisty Fawn. No help there. Tried again at Jaunty Jackalope's release WITH Hardy Heron, and still 90% of the damn documentation hadn't been updated. I'm stuck chasing around tidbits and forum posts with "well here's how you do it, LINK" only to find out that the link is either (A) for a version I'm not running, (B) assumes information I don't have, or (C) no longer available.

Tracking down how to set up a remote control reliably with Lirc is a pain beyond torture as well. I spend 99% of my time on Windows (hey, I have better things to do with my time than fight a damn OS. Windows does what I need it to do and runs what I want to run.) This is the "tutorial" for setting my remote control up under MythTV [mythtv.org]. And let me tell you right now, this thing is a shambles.

Linux people don't write clear-cut instructions for anything. This is true and I agree, it is Linux Bug #1.

It's better than Mac OS X documentation (1, Insightful)

mario_grgic (515333) | more than 4 years ago | (#30310490)

or help files for that matter. But I don't think this is really the problem. It's how often does the user feel compelled to consult the documentation or help files in their normal daily work that matters.

Re:It's better than Mac OS X documentation (2, Interesting)

ThrowAwaySociety (1351793) | more than 4 years ago | (#30310726)

or help files for that matter. But I don't think this is really the problem. It's how often does the user feel compelled to consult the documentation or help files in their normal daily work that matters.

I'm guessing you're referring to the printed documentation only.

Apple's online knowledgebase is unsurpassed, since it covers both hardware and software, and since there are so few permutations of both that it's possible to actually have comprehensive documentation.

And the built-in, offline help system is pretty darned good for basic purposes. For other purposes, it searches the above mentioned online knowledgebase, so...yeah.

Re:It's better than Mac OS X documentation (1)

L4t3r4lu5 (1216702) | more than 4 years ago | (#30310730)

Mac OS X doesn't need documentation. It is written with specific hardware in mind, and comes pre-configured for it.

Debian doesn't come with the appropriate drivers and conf files edited for my Gigabyte motherboard (and on-board sound, LAN, and chipset), my nVidia graphics card, and my PCI USB2 card. OS X doesn't need them.

Documentation is very lacking (5, Insightful)

genkael (102983) | more than 4 years ago | (#30310494)

As a linux user since 1995, I have found the documentation to be little more than it was around 2000. It's easier to do a google search than try to find an answer in a man page. Not only that, the man page rarely has useful examples, one of the biggest problems.

Re:Documentation is very lacking (1)

mikael_j (106439) | more than 4 years ago | (#30310572)

Not to mention the GNU apps that have manpages that (at least on some Linux distros) basically say "Yeah, it's a piece of software, if you want more docs install the info package for it" which is completely unhelpful when you're on a system that barely boots and you can't install packages with the system in its current state.

/Mikael (who recently installed a Linux distro for the first time in a while, FreeBSD just didn't want to play with the netbook)

Re:Documentation is very lacking (1)

H0p313ss (811249) | more than 4 years ago | (#30310676)

Not to mention the GNU apps that have manpages that (at least on some Linux distros) basically say "Yeah, it's a piece of software, if you want more docs install the info package for it" which is completely unhelpful when you're on a system that barely boots and you can't install packages with the system in its current state.

I've been there... not in a long, long time... but it left deep wounds.

Similarly, try setting up any new machine with any operating system these days without an internet connection... or with an exotic wireless card. How will ordinary mortals survive the 21st century? Let's face it, most of the planet can't tell a mac address from a big mac.

Re:Documentation is very lacking (3, Insightful)

Anonymous Coward | more than 4 years ago | (#30310592)

Compare the Linux documentation to the FreeBSD Handbook and you will see that Linux has no documentation to speak of. Perhaps that's the price you pay for having no central management, I don't know.

Oh, and can we please get rid of that awful Gnu Info crap?

Re:Documentation is very lacking (1)

Quiet_Desperation (858215) | more than 4 years ago | (#30310654)

Not to mention you need to know which man page to invoke which is *REAL* great for beginners.

Re:Documentation is very lacking (2, Informative)

Bluesman (104513) | more than 4 years ago | (#30310722)

>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:Documentation is very lacking (2, Funny)

Goaway (82658) | more than 4 years ago | (#30310928)

> 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)      - Methods for locating and parsing bits of Apache source code
Apache2::CmdParms(3pm)   - Perl API for Apache command parameters object
Apache2::Command(3pm)    - Perl API for accessing Apache module command information
Apache2::Connection(3pm) - Perl API for Apache connection object
Apache2::ConnectionUtil(3pm) - Perl API for Apache connection utils
Apache2::Const(3pm)      - Perl Interface for Apache Constants
Apache2::Directive(3pm)  - Perl API for manipulating the Apache configuration tree
Apache2::Filter(3pm)     - Perl API for Apache 2.0 Filtering
Apache2::FilterRec(3pm)  - Perl API for manipulating the Apache filter record
Apache2::HookRun(3pm)    - Perl API for Invoking Apache HTTP phases
Apache2::Log(3pm)        - Perl API for Apache Logging Methods
Apache2::MPM(3pm)        - Perl API for accessing Apache MPM information
Apache2::Module(3pm)     - Perl API for creating and working with Apache modules
Apache2::PerlSections(3pm) - write Apache configuration files in Perl
Apache2::Process(3pm)    - Perl API for Apache process record
Apache2::RequestIO(3pm)  - Perl API for Apache request record IO
Apache2::RequestRec(3pm) - Perl API for Apache request record accessors
Apache2::RequestUtil(3pm) - Perl API for Apache request record utils
Apache2::Resource(3pm)   - Limit resources used by httpd children
Apache2::Response(3pm)   - Perl API for Apache HTTP request response methods
Apache2::ServerRec(3pm)  - Perl API for Apache server record accessors
Apache2::ServerUtil(3pm) - Perl API for Apache server record utils
Apache2::SizeLimit(3pm)  - Because size does matter
Apache2::Status(3pm)     - Embedded interpreter status information
Apache2::SubProcess(3pm) - -- Executing SubProcesses under mod_perl
Apache2::SubRequest(3pm) - Perl API for Apache subrequests
Apache2::URI(3pm)        - Perl API for manipulating URIs
Apache2::Util(3pm)       - Perl API for Misc Apache Utility functions
Apache2::compat(3pm)     - -- 1.0 backward compatibility functions deprecated in 2.0
Apache2::porting(3pm)    - -- a helper module for mod_perl 1.0 to mod_perl 2.0 porting
Apache::Test(3pm)        - Test.pm wrapper with helpers for testing Apache
Apache::TestConfigData(3pm) - Configuration file for Apache::Test
Apache::TestMB(3pm)      - Subclass of Module::Build to support Apache::Test
Apache::TestMM(3pm)      - Provide MakeMaker Wrapper Methods
Apache::TestReport(3pm)  - A parent class for generating bug/success reports
Apache::TestRequest(3pm) - Send requests to your Apache test server
Apache::TestRun(3pm)     - Run the test suite
Apache::TestRunPHP(3pm)  - configure and run a PHP-based test suite
Apache::TestRunPerl(3pm) - Run mod_perl-requiring Test Suite
Apache::TestSmoke(3pm)   - Special Tests Sequence Failure Finder
Apache::TestTrace(3pm)   - Helper output generation functions
Apache::TestUtil(3pm)    - Utility functions for writing tests
App::CLI(3pm)            - Dispatcher module for command line interface programs
App::CLI::Command(3pm)   - Base class for App::CLI commands
Archetype(n)             - base class for all [incr Tk] mega-widgets
Archive::Extract(3pm)    - A generic archive extracting mechanism
Archive::Tar(3pm)        - module for manipulations of tar archives
Archive::Tar::File(3pm)  - a subclass for in-memory extracted file from Archive::Tar
Archive::Zip(3pm)        - Provide an interface to ZIP archive files
Archive::Zip::FAQ(3pm)   - Answers to a few frequently asked questions about Archive::Zip
Archive::Zip::MemberRead(3pm) - A wrapper that lets you read Zip archive members as if they were files
Archive::Zip::Tree(3pm)  - (DEPRECATED) methods for adding/extracting trees using Archive::Zip
Attribute::Handlers(3pm) - Simpler definition of attribute handlers
Authen::SASL(3pm)        - SASL Authentication framework
Authen::SASL::Perl(3pm)  - -- Perl implementation of the SASL Authentication framework
Authen::SASL::Perl::ANONYMOUS(3pm) - Anonymous Authentication class
Authen::SASL::Perl::CRAM_MD5(3pm) - CRAM MD5 Authentication class
Authen::SASL::Perl::DIGEST_MD5(3pm) - Digest MD5 Authentication class
Authen::SASL::Perl::EXTERNAL(3pm) - External Authentication class
Authen::SASL::Perl::GSSAPI(3pm) - GSSAPI (Kerberosv5) Authentication class
Authen::SASL::Perl::LOGIN(3pm) - Login Authentication class
Authen::SASL::Perl::PLAIN(3pm) - Plain Login Authentication class

[about a hundred pages of Perl modules elided]

_exit(2)                 - terminate the calling process
_longjmp(3), _setjmp(3), longjmp(3), longjmperror(3), setjmp(3), siglongjmp(3), sigsetjmp(3) - non-local jumps
_nc_free_and_exit(3x), _nc_freeall _nc_free_and_exit(3x) - curses memory-leak checking
_tracef(3x), _tracedump(3x), _traceattr(3x), _traceattr2(3x), _nc_tracebits(3x), _tracechar(3x), _tracechtype(3x), _tracechtype2(3x), _tracemouse(3x), trace(3x) - curses debugging routines
a2p(1)                   - Awk to Perl translator
a64l(3), l64a(3)         - convert between 32-bit integer and radix-64 ASCII string
ab(8)                    - Apache HTTP server benchmarking tool
abort(3)                 - cause abnormal program termination
abs(3)                   - integer absolute value function
ac(8)                    - display connect-time accounting
accept(2)                - accept a connection on a socket
accept(8), cupsaccept/cupsreject(8) - accept/reject jobs sent to a destination
access(2)                - check access permissions of a file or pathname
access(5)                - Postfix SMTP server access table
acct(2)                  - enable or disable process accounting
acct(5)                  - execution accounting file
accton(8)                - enable/disable system accounting
acl(3)                   - introduction to the POSIX.1e ACL security API
acl_add_flag_np(3)       - add flags to an flag set
acl_add_perm(3)          - add permissions to a permission set
acl_clear_flags_np(3)    - clear flags from a flag set
acl_clear_perms(3)       - clear permissions from a permission set
acl_copy_entry(3)        - copy an ACL entry to another ACL entry
acl_create_entry(3), acl_create_entry_np(3) - create a new ACL entry
acl_delete_entry(3)      - delete an ACL entry from an ACL
acl_delete_flag_np(3)    - delete flags from a flag set
acl_delete_perm(3)       - delete permissions from a permission set
acl_dup(3)               - duplicate an ACL
acl_free(3)              - free ACL working state
acl_from_text(3)         - create an ACL from text
acl_get_entry(3)         - retrieve an ACL entry from an ACL
acl_get_fd(3), acl_get_fd_np(3), acl_get_file(3), acl_get_link_np(3) - get an ACL for a file
acl_get_flagset_np(3)    - retrieve flag set from an ACL or ACL entry
acl_get_perm_np(3)       - check if a permission is set in a permission set
acl_get_permset(3)       - retrieve permission set from an ACL entry
acl_get_qualifier(3)     - retrieve the qualifier from an ACL entry
acl_get_tag_type(3)      - retrieve the tag type from an ACL entry
acl_init(3)              - initialize ACL working storage
acl_set_fd(3), acl_set_fd_np(3), acl_set_file(3), acl_set_link_np(3) - set an ACL for a file
acl_set_flagset_np(3)    - set the flags of an ACL or ACL entry
acl_set_permset(3)       - set the permissions of an ACL entry
acl_set_qualifier(3)     - set ACL tag qualifier
acl_set_tag_type(3)      - set the tag type of an ACL entry
acl_to_text(3)           - convert an ACL to text
acl_valid(3), acl_valid_fd_np(3), acl_valid_file_np(3), acl_valid_link_np(3) - validate an ACL
acos(3)                  - arc cosine function
acosh(3)                 - inverse hyperbolic cosine function
add_wch(3x), wadd_wch(3x), mvadd_wch(3x), mvwadd_wch(3x), echo_wchar(3x), wecho_wchar(3x) - add a complex character and rendition to a curses window, then advance the cursor
add_wchstr(3x), add_wchnstr(3x), wadd_wchstr(3x), wadd_wchnstr(3x), mvadd_wchstr(3x), mvadd_wchnstr(3x), mvwadd_wchstr(3x), mvwadd_wchnstr(3x) - add an array of complex characters (and attributes) to a curses window

[and so on]

Re:Documentation is very lacking (5, Informative)

CasaDelGato (701438) | more than 4 years ago | (#30310698)

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:Documentation is very lacking (1)

FauxPasIII (75900) | more than 4 years ago | (#30310930)

> Man pages are only semi-useful if you ALREADY KNOW WHAT COMMAND YOU NEED

-nod- Strongly agree. Something that's long been on my list of "ideas I'll get around to some day" is to build a scaffolding for a vastly more useful "help" command. That's the closest thing to a way of making command-line interfaces discoverable... and the current "help" command is only a reference to Bash internals (at least if you're using that shell, which a novice most likely is)... probably not what the complete beginner is looking for.

Re:Documentation is very lacking (4, Funny)

nomadic (141991) | more than 4 years ago | (#30310766)

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:Documentation is very lacking (2, Informative)

godrik (1287354) | more than 4 years ago | (#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:Documentation is very lacking (1)

blincoln (592401) | more than 4 years ago | (#30310800)

Not only that, the man page rarely has useful examples, one of the biggest problems.

Exactly. If you ask me, there are two layers of problem with the "man page model". The first is that it expects the user to know which command they want to use (so they can call up the man page for it), and the second is that (as genkael wrote) the man pages generally describe the syntax of the command, not how to accomplish various real-world tasks with it.

There are certainly times when I already know what command I want to use and what parameters I want to pass to it, but usually if I'm reading documentation it's because I know what task I want to accomplish, not necessarily how to map that task to a command and its associated parameters.

Why not? (0, Redundant)

clone53421 (1310749) | more than 4 years ago | (#30310496)

The PHP documentation is online, and you can comment on every page. Sometimes it’s really helpful to see what other people have said about a function, how they used it, or problems they had and how they worked around them.

A static documentation doesn’t have any of this. You get what you get, that’s it.

Don't like man pages. (5, Interesting)

theNetImp (190602) | more than 4 years ago | (#30310500)

I find man pages to be poorly written, and difficult to understand most of the time. I tend to use google to find people who are discussing it in plain english...

Re:Don't like man pages. (1)

chiangovitch (1371251) | more than 4 years ago | (#30310596)

I find man pages to usually be concise, to the point, and extremely helpful. I hate it when I find there is no man page for a program for which I have a question. I remember when we got our first Unix Sytem 3 v7 system in the '80s. The entire sum of the documentation consisted of one binder of man pages, and one binder of troff-formatted documentation on things like flex, yacc, troff, etc. And it was sufficient for an intelligent neophyte (yours truly), but it certainly wouldn't be suitable for Grandma or my accountant.

Re:Don't like man pages. (3, Interesting)

daid303 (843777) | more than 4 years ago | (#30310752)

Manpages suck for the average programmer. You're above average (so I am) but lots of the people I work with struggle with manpages. They seriously lack examples.

And then there are the man pages that say "look in header file X for the rest", and of course the headerfiles don't contain comments. So you'll have to figure out on your own what "FBIOGET_VSCREENINFO" means. (The V stands for 'variable', which google could tell me)

Re:Don't like man pages. (2, Insightful)

Anonymous Coward | more than 4 years ago | (#30310692)

Perhaps that's because you have only seen Linux (or Gnu) manpages. Take a look at the (Free-)BSD manpages and you will be pleasantly surprised.

Re:Don't like man pages. (1)

supremebob (574732) | more than 4 years ago | (#30310884)

I'm not a fan of man pages... they seem to be written by programmers FOR programmers. When I'm reading one, I usually don't want to learn the 50 command line switches that the command has. I just want an example of how to use the command for my particular purpose, which is much easier to find with a Google search.

Seriously, guys... If you added a one page "Examples" section at the bottom of the man page, it would be infinitely more helpful for end users.

Does Linux have poor documentation? (-1, Flamebait)

Anonymous Coward | more than 4 years ago | (#30310502)

Does the pope shit in his hat?

user mentality differs now~ (1)

Synflex (5489) | more than 4 years ago | (#30310508)

The fact is, Google in most of the times, provide a list of posts in some forum with a working sample code.

Face it, users nowadays weren't looking to understand the process, they just want a quick solution (even if it risk installing a rootkit).

Think Ubuntu Community. sigh~~~

using Google before a man page? (1)

wiredog (43288) | more than 4 years ago | (#30310518)

Yes. Why not? Most commercial software ships without documentation too. If I want to figure out how to do something on Mac I google for it first. Similarly for Windows. When I was first starting out, Back In The Day (well, mid-90's) I bought "Running Linux" and "Linux in a Nutshell" (which, IIRC, was compiled from man pages) from O'Reilly, and read those rather than using man pages.

And good luck with Google, too (5, Insightful)

edraven (45764) | more than 4 years ago | (#30310528)

As often as not, the only hits you get are posts in forums where someone is asking the exact same question you need answered... and getting no replies. Since 2005.

Re:And good luck with Google, too (1)

theNetImp (190602) | more than 4 years ago | (#30310598)

I agree googling for the answer is difficult. Usually the answer isn't on the first few pages, and you have to dig through 4-7 layers of pages before you find it. More often than not you get sent to forums where the question is asked, but in order to see the answer you have to pay for access to the site. So much for open source.

Re:And good luck with Google, too (1)

Dr_Barnowl (709838) | more than 4 years ago | (#30310662)

I just routinely click on the "X" thing to remove every result from expert-sexchange from the list ; worse than useless, they clutter up otherwise potentially useful result lists. Perhaps if enough people do the same thing, their PageRank will suffer enough that they die.

Re:And good luck with Google, too (1)

clone53421 (1310749) | more than 4 years ago | (#30310786)

You know, you can scroll all the way down... past pages and pages of unrelated garbage... and the “expert solution” (or whatever they call it) is at the bottom of the page. They hide it there so you think you have to register.

Re:And good luck with Google, too (-1, Troll)

dunezone (899268) | more than 4 years ago | (#30310810)

You can scroll to the bottom of the page listings at Experts-Exchange responses and you will see the answer. Its just filled with clutter to confuse you into buying a subscription but the answers to the question are literally at the bottom of the page.

Re:And good luck with Google, too (1)

LordKronos (470910) | more than 4 years ago | (#30310952)

I've usually found that website to actually give pretty good answers to the problem. Granted, if google returns pages dealing with problems other than your own, yeah, that's not very helpful. However, I've generally found that if my search term is good enough to return meaningful results from other websites, the links to expertsexchange is usually as good, if not better, than a lot of other websites. You just need to know the "secret" that all of the answers are visible in plain text way down at the bottom of the page.

Re:And good luck with Google, too (1)

L4t3r4lu5 (1216702) | more than 4 years ago | (#30310846)

I don't find paying sites; I'd pay if I could guarantee an answer.

What I find is "Oh, open bash and enter grep I lspsi > 0 !foo and point ndiswrapper at the firmware from the windows driver"

I read it and think to myself "Great. Now I know how my users feel. WTF does that mean?!" I'm sure all the information I need is there somewhere, but filtering through all manner of gobbledigook to find out what the hell someone is saying often takes more time than fixing the damn problem!

Re:And good luck with Google, too (2, Insightful)

godrik (1287354) | more than 4 years ago | (#30310850)

And you are exposed to none compatible solutions. The number of doc out there that still use insmod/rmmod instead of modprobe is high. The number of solutions that tell to install software manually instead of using the one from your distro repository is high. Google is good to get a basic understanding of the concept and problem. Then read the manual (not only talking about man pages)

Re:And good luck with Google, too (0)

Anonymous Coward | more than 4 years ago | (#30310922)

Or worse, answered with information that was only relevant... in 2005. The other day I was trying to find out why cfdisk won't let me make a partition bigger than 681 GB. There's lots of posts about how to partition your 60 GB hard drive, none about dealing with 2+ TB. Often the answers I find in posts for technical questions like that are out and out wrong.

Come down to using Google? (0)

Anonymous Coward | more than 4 years ago | (#30310534)

As a Linux neophyte, google has *always* been my choice. It's been my experience that man pages don't provide the context and examples I need to use tools completely foriegn to me. Of course...I've never relied on MS help files either. Prior to Google searching, my path to success involved knowledgeable folks around me and actual written documentation. I think every OS and application author or publisher should consider reworking contextual help so new users have quality help that's easily found. Like a link to Google in every app.

Depends (0)

Anonymous Coward | more than 4 years ago | (#30310550)

do new users even know Man pages exist? also another issue with man pages, I think, is for new users is that they are written for other technical users on the whole and not your aunt vera.
Anon Coward.

yes yes (1, Funny)

Anonymous Coward | more than 4 years ago | (#30310554)

I google for man pages.

Google, Safari, Addison-Wesley, Sun (1)

Bigbutt (65939) | more than 4 years ago | (#30310562)

Yea, generally when I'm trying to figure something out, I'll do a search of the 'net for a quick answer and then reach for an O'Reilly (via Safari) or Addison-Wesley book for in-depth knowledge.

The problem for me is that the man page is either a paragraph or two and not much help or 35 pages of incredibly detailed information that's difficult to parse. I'll do a google man page search at times just so I have an easy way to browse the page.

A man page doesn't provide a tutorial and many times don't even provide examples of usage.

[John]

Search Engine De-optimization (1)

Ukab the Great (87152) | more than 4 years ago | (#30310568)

Contributing to the problem of finding good documentation is the fact that LUGs, distro companies, etc all mirror same crappy outdated collection of HOWTO's and man pages on their websites, and thus the newbie desperate to find out how to do something ends up with Google page after Google page of the same useless stuff.

The Culture needs a slight change. (1)

Icegryphon (715550) | more than 4 years ago | (#30310570)

Is it really as bad as these blogs paint it?

Sometimes I can be, I have seen some bad documentation even on Windows apps.
It really is the whole programming culture that needs to have a mindset change.
They need to care about Documentation more so other people can pickup where they left off
It also saves programmers the time of having to answer needless questions.

Has it come down to using Google before a man page?

If you deal with obscure software, yes.
I know I had to use google quite a bit the first time I was building lapack and cblas.

Re:The Culture needs a slight change. (2, Funny)

godrik (1287354) | more than 4 years ago | (#30310892)

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.

Is this really such a sin? (1)

Zarrot (1149415) | more than 4 years ago | (#30310582)

All documentation sucks now a days. I default to Google for documentation on everything. Microsoft doesn't even really ship docs anymore they just link through to their web documentation. It's just the way of things now. You'll get more and better info from thousands of bloggers and forum posters than you can expect from any doc team.

The short answer: it depends. (1)

Scholasticus (567646) | more than 4 years ago | (#30310588)

Well, if you're talking about official documentation that comes with a particular application, or HOWTOs on various subjects, I think there is a lack of good documentation for beginners etc. in quite a few areas. But most distributions have help forums, (some better than others) and that plus a little googling provides lots of very helpful information for the less experienced users. Remember back when any application you bought came with a big fat manual (the paper kind, I mean)? I'm thinking of when I was using WordPerfect 5.1 in DOS. Well, those days are gone, and the "missing manuals" which you can buy are both very expensive and sometimes innacurate. Sure, GNU/Linux and associated applications and DEs could use better official documentation, but there's a lot of good information out there as well.

Yes. (3, Insightful)

LWATCDR (28044) | more than 4 years ago | (#30310602)

Writing documentation is hard work and is boring. It is also thankless.
The funny thing is that documentation for the most technical programs tends to be very good. PHP, Perl, Apache, Postgres, and MySql all do seem to have good documentation.
Gnome not so much. Many other apps also seem to lack good docs. X is just a disaster. It is documented but it is still a pain when things fail they are a huge mess to fix.

Re:Yes. (3, Informative)

eldavojohn (898314) | more than 4 years ago | (#30310704)

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.

Yes (2, Insightful)

DontBlameCanada (1325547) | more than 4 years ago | (#30310604)

In a word, yes, many/most linux docs suck.

Man is useful once you understand the basics of how a command works. However, if you're sufficiently green, decoding the language in many of the man pages is difficult. When executing certain system management tasks as root, a mistake can be catastrophic. Google will pull up the man page for you, but also the infinitely more educational blog and faq pages that decribe what a command does, when you use it and how to trouble shoot problems encountered with it.

The problem with Google, is the non-official blogs and faqs frequently reference older version of the command line tools bundled in the latest distros. Occasionally, the tool author radically alters the tools between releases rendering the non-official docs inaccurate... Then the neophyte/newbie hobbyist is up the creek with a paddle.

Tutorials (0)

Anonymous Coward | more than 4 years ago | (#30310606)

Tutorials are a fucking problem. That and pointless screencasts. Nobody can refer to documentation to get the facts needed to solve a problem anymore. They all need the problem *directly solved for them*.

Coupled with people's insistence on using "new media" like videos to "teach" information that should be written clearly as a reference (rather than a "how to do it" guide) and the amount of totally unqualified/unskilled people who insist on *TEACHING* (usually to gain attention, or worse; AdSense revenue) we're creating a generation of terrible IT workers with no problem-solving or research skills whatsoever.

Tutorial-based development is practically the leading paradigm for new graduates doing monkey-level coding work nowadays.

Google is a step up (0)

Anonymous Coward | more than 4 years ago | (#30310620)

Come down to? Man pages are a standard from 30-some years ago, intended for expert users (the only kind there were back then).

Of course, if we could all agree on a standard that meets today's needs, that would be another step up. A place with natural tools for a help forum and links to publisher documentation to get user-tagged and wiki-edited into user-friendly, version-referenced documentation over time, and more importantly, one which was the consensus one-stop-shopping place for this kind of stuff. To get the user base, it couldn't be restricted to Linux tools - it would have to be universal.

Google can be more specific (2, Insightful)

Dr_Barnowl (709838) | more than 4 years ago | (#30310642)

Getting the detail you want out of a man page is often harder than finding the relevant bits on Google. And of course, man pages don't help you at all if you don't know which command you want to be using ; and let's face it, for a given task, there might be three ways of doing it.

I'm still a relative Linux novice despite having used it for some time now, but I'm a programmer and prepared to slog through documentation and web pages to get things going.

Example - the prune argument of find. I'll give a limited-edition photon to the first person who figures out the way to use the prune argument to produce a list of files that _doesn't_ match a particular path pattern, solely limiting themselves to the man page, without using Google.


find . -path '*/not-these' -prune # This does basically the opposite of what you'd expect it to.

Yes, I know how to do it NOW. Well, Google remembers which page I found most relevant for the search terms that eventually found the right way.

Re:Google can be more specific (1)

langelgjm (860756) | more than 4 years ago | (#30310828)

If you want to exclude files matching a certain pattern in their path, wouldn't use just use something like "-not -path '*/excluded_path'"? I do that to exclude certain file extensions (but with -not -name '*.extensions'). According to the man page, prune determines whether to descend into directories at all, which is a different issue.

But yeah, find is kind of a fscked up command on the whole... doesn't really work how you think it should :-)

How is this different from Windows or Mac? (0)

Jace Harker (814866) | more than 4 years ago | (#30310646)

True, the built-in Linux documentation is often lacking. But in spite of that, it's much, much better than the built-in help files for Windows or Mac.

No matter which OS I use, Google is always my first stop for technical help. The difference between them is that with Linux, I usually find a helpful site almost immediately (usually on the Ubuntu Forums). With Windows, the best help I can find is usually some obscure, confusing entry at the Microsoft Support website. Ick.

man page != end user documentation (1)

theonlyholle (720311) | more than 4 years ago | (#30310648)

The question in the summary shows the extent of the problem. No, a man page is not proper end-user documentation. It's great for a trained IT professional who quickly needs to look up the syntax for a command. But for my mom or my wife's dad, even getting to the man page is a challenge - and to get there, they need to know that man pages exist. Are there even man page viewers for the desktop? Ones that are readily accessible and preinstalled with the default system? But I must come to Linux's defense, too. The documentation on my latest Windows system is not much better, except that a help system is built right into the desktop. It's the availability of third party printed documentation that makes the difference.

Ironically, (2, Insightful)

aussersterne (212916) | more than 4 years ago | (#30310912)

man pages used to be great. They used to absolutely rule and tell you exactly how to use any part of the system. Now, most things are lacking a man page entirely (man openoffice, man gnome, man kde, man evolution) and the man pages that do exist either tell you nothing or tell you nothing useful.

And, even more ironically, there used to be dozens of desktop manpage viewers, most notably xman from the basic X applications toolset installed on all UNIX and Linux desktops with X. You could even type "man:command" into most Linux browsers and read the manpage. Now none of this exists; it has been TAKEN OUT under the theory that user access to documentation or utilities of this kind is bad for some reason.

Do they mean Linux or the distro? (1)

G3ckoG33k (647276) | more than 4 years ago | (#30310666)

Do they mean Linux or the distro? This is an important distinction here. I never looked at Linux' documentation; didn't even know it had one except the comments in the code. But, with the bewildering number of distros, I can see the issue there to any newcomer.

Well, No Shit (5, Insightful)

bsDaemon (87307) | more than 4 years ago | (#30310678)

That's because its really difficult to determine what's "Linux" when you're talking about Linux. What works on RHEL/CentOS won't necessarily work exactly the same on Fedora, and will probably be way different than on a Debian box.

Contrast this, however, to one of the BSDs, say FreeBSD, which I am the most familiar with. Let us take a look here: http://www.freebsd.org/docs.html. All of these documents ship with the OS, so if you don't have a network connection (for instance, you need the docs to help you set it up), then you have them there as well. The FreeBSD Handbook covers everything from installation to configuring BGP.

There is a separate Developer's Handbook (which even contains a primer on x86 asm), a Porter's Handbook, etc. The docs that ship with the OS include even The Design and Implementation of the 4.4BSD Operating System, which is somewhat dated at this time, but still a great help in theory.

Then, of course, there are the man pages that everyone always mentions, which are awesome, but don't really help make the point I'm putting forward. Of course, the fact that FreeBSD can ship such thorough documentation is because FreeBSD is FreeBSD anywhere, where "Linux" is not. So, perhaps the problem isn't with "Linux," but with certain distributions not taking documentation seriously enough for the various common tasks and interfaces.

What I'm really getting at is, I should not have to Google around for random blogs and wikis to find out how to do a common task that I may be getting to for the first time, hope that I can find an answer, and that the source can be trusted. Any of the distributions which have any sort of commercial or foundation backing at all, really should just bite the bullet and hire on a few technical writers to actually make proper documentation, and then keep it up-to-date. Hell, even Microsoft updates their online help files, and most tasks in Windows are straight forward enough that only 4th grades and 60 year olds need to ask about it.

Relying on GUI config tools, DHCP, and other magic to keep "newbies" from needing to actually learn anything is counter-productive and isn't going to help create new professionals. "RTFM" shouldn't be a put down or a dirty word, but TFM needs to actually contain TFInformation. Is that really so much to provide?

Maybe (1)

Kjella (173770) | more than 4 years ago | (#30310680)

I'm sure there's a lack of GUI guides - most advice is to paste some obscure commands on the command line. But my biggest issue has been documentation that's just not relevant anymore. When they refer to switches that don't exist, configuration files that have changed formats, dialogs that aren't where they're supposed to be, or where basically the whole way of doing things have changed. Or it refers to an ancient command line way of doing it because the GUI tool didn't support it, but now it does.

Sometimes, the documentation is the right answer to the wrong question. For example, I've struggled with xorg.conf to make it recgonize all my mouse buttons and eventually it did, but that should have been autodetected (or from a device list) and a user-friendly mapping tool to let me choose what they'll mean. More "just work", less "documentation you must read because things don't work" really.

Another good example is the media players. I've fiddled with tons of switches there when what I'd like to do is double click and have the file play. It's great that they're there, if you need them. But it's not better manpages I want...

OSS is bad, but is commercial so much better? (1)

NtwoO (517588) | more than 4 years ago | (#30310694)

My experience with OSS docs is that it is often much better than the docs of Propriety products. The rationale that explains this, I think, is that OSS docs/faqs etc if present, is at a level that ensures that the developer does not have to answer too many questions from noobs. With propriety software the focus is often "We need docs to say that we have a complete package that we can sell" That means that the docs are often absolute drivel and takes you no further than what the UI already provided. At the worst it is just a series of screenshots of the menu's stating the obvious, like "File->open: this opens files". Both camps have examples of brilliance and of drivel, but the propriety products surely excel in the drivel department!

Documentation (1)

bmo (77928) | more than 4 years ago | (#30310720)

It's not the volume that's lacking.

There is no shortage of doorstops for GNU/Linux. There is also no shortage of web based documentation.

However, there is a crapload of BAD documentation.

--
BMO

Beginner looking to do better (0)

Anonymous Coward | more than 4 years ago | (#30310742)

I'm a Linux beginner with Ubuntu installed in VMware and considering buying a laptop to run Linux exclusively. I don't feel like I know enough to jump in all the way just yet. Google is useful if I know what I'm looking for, but at this point I'm not sure what I don't know yet. Once I know it, though, I intend to educate others, like my non-techie fiance and parents. (incidentally, my Mom loves the idea of Linux as a community created OS)

Is there a list of benchmarks for what I should know as a basic user and what I should learn next?

Silly Goose, Google is the "documentation" (0)

Anonymous Coward | more than 4 years ago | (#30310746)

If Google doesn't know, it is un-knowable.

Documenting shitty software is futile (2, Interesting)

gzipped_tar (1151931) | more than 4 years ago | (#30310750)

If a software solution is crappy enough, it is impossible to write document for it. If a program has to be *endured* rather than enjoyed, all its documentation can do is either reinforcing the shittiness experience by point out *how* and *why* it already sucks and un-amendable (if the doc is correct), or dumping more crap on top of that (if the doc is incorrect).

I'm looking at you, GNOME. I used to be a GNOME user but I gave up. The docs was barely useful for anything. I wanted to configure GDM and there's no explanation of those arcane XML shit and event hooks. The conf files were scattered here and there, and guess what, the infamous, incomprehensible gconf that actually brags about being modeled after MS registry! I finally got the idea that the devs simply gave up the idea of explaining their un-explainable clusterfuck already. I don't use a DE anymore.

Mod me however you want. I'm not a karma sink and I don't save it for an afterlife.

oh please (0)

Anonymous Coward | more than 4 years ago | (#30310760)

Maybe some comparison to windows' help files would apply to these people.

What I see in everyday use of computers is that the end user experience is primarily based on culture rather than some completeness of built-in assistance system.
Googling answers to common issues of the system is a just next step to asking some techie's advise.

It's called engineering (4, Interesting)

thethibs (882667) | more than 4 years ago | (#30310774)

The resolution to the documentation problem is simple. I use it on my projects and when I managed programmers, I made them do it. Unfortunately, it needs discipline--the difference between programming and engineering--which is in short supply in the FOSS community.

The resolution is that you write the relevant section of the user manual first, have the client review it for clarity and sanity, and then make the software do exactly what the manual says.

Pause to recover composure

What could I be thinking?!

Not just beginner to apprentice. (5, Interesting)

aussersterne (212916) | more than 4 years ago | (#30310776)

I've been a Linux user since 1993 and the state of Linux documentation today is worse than ever before if you don't happen to be an actual coder on a specific project reading project documentation for it in order to facilitate your work and contributions.

Back in the day, there were manpages, info pages, comprehensive documentation at /usr/doc or /usr/share doc for specific packages, and documentation files in nearly every source directory that you compiled yourself. You could also pick up just about any book on UNIX (System V Bible for SysV-like distros, or various BSD books) and apply much of what was said to Linux as well.

Everything was well-understood and common to the general state of things in the UNIX world and if you didn't understand something, a quick apropos/man or info or visit to /usr/doc or /usr/share/doc would result in enlightenment.

I'm a Red Hat/Fedora user since Red Hat 4 (Slackware before that) and as a 25-year UNIX veteran, I often feel like I have no idea what's going on in (for example) the init process, X configuration, desktop management, app resources/configuration, etc. Where are the dotfiles located? Where are the /etc components? What are the command-line arguments? Where are the manual pages? What documentation does exist is generally in the awful "Help Tool" format (click Help -> Help Contents in an application window and get a lot of prose for beginners). This documentation typically offers NO INFORMATION beyond the navigation of the user interface for the application. Nothing on system resources, locations of configuration files, dependencies, APIs, command line arguments, or anything that would allow you to either troubleshoot or modularly re-use the software item in question.

The system-level stuff (PackageKit, PolicyKit, SELinux, Udev, HAL, Plymouth etc. etc.) does not offer any clear location for configuration and typing for example "man selinux" brings up a couple of paragraphs with no detail. It refers to a pile of other manual pages, none of them installed by default. There is no overview. And SELinux is probably the most transparent of all of these.

The desktop is completely unmanageable if something breaks; the dotfiles are not in any concise location. gconf-editor is not installed by default and even after you do install it, there's no documentation on the options that it contains. It's not clear how to cause a command to execute on startup. You can go to GNOME startup options in a menu through which you have to use a GUI program to "add" things to the startup process, but the environment that's being configured for the processes spawned this way is not documented and many attempts to execute commands using this method fail.

More and more it seems as though I am constantly using find and grep either in all dotfiles in a directory or as root through the entire /etc, /usr/share, and /usr/lib directories to identify through keywords or binary strings either binaries or text files relevant to tasks I want to accomplish, then paging through them or opening the binaries up in a hex editor to try to grok what I need to change through sheer intuition.

Yes, I suspect there is documentation "out there" somewhere, but spending an hour trying to Google where it is located in each instance is an hour that I already don't have and that now can't go toward actually reading and grokking the documentation in question. But it appears to be just too much to provide easy directions to the technical documentation that exists, if it exists, in each case.

There is a definite ethos of "try to hide the system from the user" that has emerged in Linux and it does not make me happy, as is obvious here. I now spend several days each Fedora upgrade trying to bang my personal system into the shape I want it to be in. It used to be really simple to upgrade, and it was one of the greatest things about Linux. Just transplant your home directory, save a copy of important dotfiles and /etc files, make the one or two well-documented minor changes between config file versions, and away you go. Couple of hours.

These days I spend hours playing with Udev, HAL, PolicyKit, and GNOME, often feeling more like I'm fighting a Windows machine with its typical determination to hide all interfaces but the desktop interface from me and prevent me from controlling my own system in the way that I see fit.

Yes, rant. I think what I'm saying is that there's nothing inherently wrong with the new Linux. It's a great desktop experience out of the box for users. But we're losing many of the tremendous traditional advantages of UNIX: total openness, total documentation, easy re-use, easy system management, and all it would take is a shift in mindset to imagine users beyond the vaunted "users" as in "Users don't want to see this stuff. Users just want it to work. Users don't ever want to have to read. Users don't want configuration options. Users don't want to change their system. If this doesn't sound like you, you are not one of the users and are free to use some other system."

For me that other system may be Mac OS X after all these years as a Linux user, simply because if I am to have the closed system mentality operating on my desktop anyway, Mac OS X gets it more right "out of the box" than any of the others, while still offering a UNIX-like environment.

Think in terms of _subsystems_, please! (1)

figmagee (1183813) | more than 4 years ago | (#30310794)

My biggest gripe is when a complex subsystem (e.g. audio in recent distros) lacks a "10,000ft perspective". Sure, I can read about all the bits and pieces, but there's simply nothing that treats it as a _system_. Fine to handwave about "this maps this to that", but for crying out loud how much effort does it take to draw a )(*^&)^ block diagram showing the sense and direction of said mappings? Another prime example: KDE (and perhaps Gnome) initialization. How about a step-by-step runthrough of how the various blocks are started, what starts them, where they all read configuration data from, etc, etc. If this exists now, my apologies, but I spent a horrendous amount of time working out how a desktop session figures out the paths of its .kde and Desktop directories from square one. It's _almost_ explained properly in several places, but until I wrote a script to dynamically modify ~/.config/user-dirs.dirs at KDE login it insisted on defaulting back to the "well known" directories for the initial phases. Can I really be the only person who needs to keep their KDE desktops disjoint across host machines when using a common home directory?

Do you even have to ask? (1)

BenEnglishAtHome (449670) | more than 4 years ago | (#30310802)

To answer the question in the summary - You're kidding, right?

Linux docs are pretty much terrible. I didn't RTFAs but I'm pretty sure I can imagine what they say.

The web forums are disorganized. The plethora of "just different enough that this trick won't work on that one" distros dooms to failure even serious attempts to bring order to this world. The traditional man pages don't have useful examples or appear to have been written as condensed cheat notes formatted for scrawling on the palm of your hand before going into an exam. Yes, you go to google first if you want to have a ghost of a chance of figuring out your problems.

Now, don't get me wrong. There are some stunningly nice examples of Linux docs out there. There's just far too few and they're hidden in the giant haystack of crap, stuff that doesn't apply to your distro, and just plain wrong advice apparently written by griefers.

Interesting timing on this story, though. I ran across a good example last week. I'm having trouble with trying to get video to work in Ubuntu Hardy LTS on a machine with a poorly supported ATI integrated video setup. After much reading, I finally find a few pearls that talk about bypassing X and using framebuffer output. Supposedly VLC and mplayer can both do this.

I'll spare you the gory details. But if you want to test this, I challenge anyone to locate online a reasonable set of command-line examples that show how to start those programs in this mode, examples that can be understood by a reasonably competent user who simply hasn't dealt with this stuff before. The couple (and there were *just* a couple) of command-line examples I was able to locate after hours of searching made all sorts of assumptions about the command-line competence of the reader.

Ultimately, the docs just weren't good enough to do the job. That is way, way too common in Linux-land.

If you write it will they come? (1)

Neil Watson (60859) | more than 4 years ago | (#30310804)

How many people actually study the manual that come with any product? I've been using Linux for so long that I'm not certain what would go into a beginner's guide to Linux. Does Windows come with such a document? Do Windows licensees find it useful? Do they even read it?

Well these people are what are missing! (1)

cybereal (621599) | more than 4 years ago | (#30310882)

The open source community is essentially a huge collaborative composition of people with various skills and interests that drive the results in a direction that is essentially a function of all those participants.

So, if you are some clever blogger who points out that the documentation is lacking for a certain group of people then the reason for it is obvious. None of the active participating components are people who care about the type of documentation.

The fundamental problem with this style of production is that only the manufacturers will be consistently pleased with the results. Today many people are interested in the software but unable or just unwilling to participate in its creation. That includes documentation of course. So until they are able to participate somehow, their interests will rarely, if ever, be represented.

In a way this is where commercial entities could really benefit this system. A commercial entity has interests beyond their own. In fact, in most cases their interests for the production are entirely outside their personal interests. A commercial entity that wants to rely on, say, KMail for their mail client in some one-off OS based on Linux may have a customer-base that is largely non-technical. Perhaps they are selling network kiosks to elderly or something. They will be particularly interested in proper documentation or help systems that appeal to those highly uninitiated.

But what happens with those actual real commercial entities with real needs for these types of missing components? It seems that they have a tendency to branch and the work they do that would benefit the average consumer of this software never ends up back in the main lines. Maybe because the mainline maintainers don't care, don't like it, or maybe because of licensing issues or perhaps... perhaps nobody gave it any thought yet.

At any rate, it still boils down to the same thing. The a classic "OSS" community developed project will generally only have features that are desired by the contributors. If you're lucky you'll have some contributors that seek to look out for others' interests but that seems to be incredibly rare in this subculture.

If maintainers of software cited for lacking this kind of documentation care about this issue, they should be proactive about it. There is an entire class of concerns that will rarely be raised by the sort of person able and willing to contribute to an OSS project. These concerns include aspects of UI design that benefit less technically savvy individuals and, of course, user friendly documentation. If the maintainers want to excel in the production of their software they need to reach out for these types of features. Find people who can provide the materials but don't know or want to know the processes involved in making the contributions themselves. Find commercial entities that have already done the work and try to integrate what they produce, or ask them to do it.

and those undated, irrelevant web docs (0)

Anonymous Coward | more than 4 years ago | (#30310890)

I wonder how many millions of man days have been squandered trawling through outdated (and irrelevant) documentation because the author or poster could not be bothered to put a date on the document, or to specify which version of the software it refers to.

And all those all but abandoned websites which claim to list Linux friendly hardware but which list only antiquated items which can't even be bought in the shops any more. You would be doing the world a favour if you deleted the whole site. And don't even bother to explain that someone somewhere might possibly still have a need to configure Ubuntu 1.0 using a piece of junk sold in the nineties.

But maybe the worst type of documentation is that found in forums which ostensibly discuss problems and supply answers. In my experience, one can find hundreds of web forums in which the simple most obvious questions are answered (ones where the person asking the question could have found the answer for themselves in a trice) but the difficult questions are asked over and over again but nobody has the answer. Why doesn't the developer document their own software? Why when i search for documentation for a driver does Google take me to countless forums where the blind are leading the blind? Who links to forums where a hundred people all have their say, but none actually resolves the problem?

Do Microsofties leave all that crud lying around the Internet to sap the will of the unwary Linux newbies?

Date your documents. Make it clear right up front which particular bit of software and which version your documentation refers to. If you know full well that there is a separate rival project, name them and include a link. Don't waste everyone's time trying to pretend that your project is the one and only, while you know full well that there is another project which does a better job.

How many times do I have to read about ndiswrapper before I actually discover the name of the native Linux driver I need?

If you are one of those responsible for this sorry state of play, shame on you. You haven't helped anyone. Your contribution is just the spanner in the works.

Does the avg user actually require man pages? (2, Insightful)

HockeyPuck (141947) | more than 4 years ago | (#30310940)

I would assume that the average user doesn't use the CLI. Whether in windows or linux, so why should we assume that the average user would even look at man pages. Man firefox? Man calc/writer/impress? Doubt it. Take openoffice for example... let's say I want to create a textbox, so I go to the landing help page for openoffice.org and I'm presented with 4 textboxes,

-Complete Documentation Wiki
-OOo FAQ on the Wiki
-OOo Manuals on the Wiki
-Documentation Website

How is the avg user supposed to know which one to search in and the results are just a output of a google search. It would be nice if it OO.org provided more information or catagorized the output along the lines of tutorials/videos, manuals etc rather just whatever google spits out.

And OO.org is one of the better sites.

Load More Comments
Slashdot Account

Need an Account?

Forgot your password?

Don't worry, we never post anything without your permission.

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>
Sign up for Slashdot Newsletters
Create a Slashdot Account

Loading...