I'm a MS Windows user/network manager/developer (C/C++) and I'm currently trying to get into Linux for a second time.

So far I have to say that my experience has been more or less the same as during the last (abortive) attempt which is that I just cannot find any good, clear, up-to-date and authoritative documentation about anything.

I'm sure that part of the problem is my own ignorance/naivety. Apart from a little UNIX experience at university I'm a complete newcomer and the early stages are bound to be a little fraught.

But I'm equally sure that this isn't the whole story. My impression of the documentation I have been wading through is that the authors tend to make all manner of assumptions (as to the reader's prior knowledge) without realising it, with the result that the naive reader (like me) gets stuck or lost and generally can't seem to get anything done.

For example, I've been trying to set up VNC remote desktop on a CenOS 6.2 box for a couple of days now with zero success. Should it really be this difficult for someone who, although a Linux beginner, is reasonably technically savvy?

As an interesting contrast, I've been setting up a Cisco router recently. This has been my first taste of the Cisco IOS and it's certainly quite intimidating to begin with. But there's good solid documentation out there in droves and, if you're prepared to spend a little time with it, you can make progress. It seems to the me that the unwitting 'assumptions as to the reader's prior knowledge' are not present to anything like the same degree.

It may or may not be a fair comparison but it certainly is a contrast.

I'm aware that all of this might seem carping or even offensive but I'm not just trying to 'have a go'. I really would like to get into using Linux OSs and can't understand why I find it so difficult.

Is there a systemic problem with Linux documentation or is it just me?

Cheers, Ian.

No, it's not just you. Personally, I consider most Linux documentation about the worst of any Unix. Man pages are often written, apparently, by academics for other academics, making them useless to most people.

http://xkcd.com/912/

is one indication of the problem.

Though developers have told me that for programming, it's not the case, for system administration, Windows is far superior to Linux in my opinion.

The BSDs are also known for good documentation. For me, it was a great deal of culture shock when I switched from a BSD job to Linux job---one of the first servers I looked at had a bunch of services running. In FreeBSD, I would have typed man <service_name> and found out about it. In Linux, I started with man <name> to see there was no man page. (Nor info page). There was a useless line in /usr/share/doc.


HOWEVER---again, IMHO only, it is getting better. Not commercially--I think that unless the RH doc authors are being paid to ensure that customers pay for support by making available documentation difficult to use, they should be fired. If their real job is make difficult to use docs, ensuring that customers pay for support, they deserve raises.

The non-commercial distributions, on the other hand, specifically Arch, Ubuntu, and Debian, have some excellent articles on their forums and wikis.

Once again, this is only my opinion, but, as someone who has frequently been quite frustrated by either lack of documentation or poor documentation, I have to generally agree with you. Far too much seems to have what are written as self-standing instruction, when, to complete said instruction will require another 20 minutes of googling.

It's harder for me to judge now, as I'm more experienced---for example, looking at the first line of the ifconfig man page makes it quite clear to me. When I first started, I found it useless. Also, and perhaps, this is, this time in my not at all humble opinion, one of the most important things, many of the man pages now have an EXAMPLES section, which is normal in any even mildly complex BSD page. For example, years ago, the tar man page didn't have it, but does now.

So, I agree with you, but _do_ feel it's gradually improving.

One big problem, that is probably less of a problem now, is that in the old days, if you complained about a man page, you were usually insulted for your lack of ability. To me, it was an example of the emperor's new clothes, no one had the nerve to say, this documentation is horrible.

Quote:
Often, people get hung up on looking for documentation specific to the distribution they are using. Even worse, they get sucked into the "Perfect Server" guides, which many of us consider to be abominations.

When I am trying to set up or troubleshoot a service, I tend to include not only RHEL-type documentation, but Gentoo and Debian/Ubuntu documentation as well. As long as you can recognize package management-specific instructions (e.g., rpm/yum-specific (RHEL) vs apt/aptitude-specific (Debian) vs portage/emerge-specific (Gentoo)), you can navigate the documentation and find what you need.

Also, don't look at just one source of information. Study and compare at least two documents on the subject. Often, one author will explain something in a way that is meaningful to you, whereas another author's explanation may only make sense if you already understand the subject. The second case is often true with manpages, which most of us consult because we don't recall the option we need to do something.

Last, and possibly most important, if you are going to manage a linux system in a meaningful way and your knowledge is limited, then be sure to purchase a basic book for the distro. For example, Christopher Negus's Linux Bibles now come in all sorts of flavors and typically include excruciatingly detailed instructions for completing typical administrative tasks. Where to Find Answers contains a listing of EL-specific books.

Linux administration initially has a vertical learning curve, but it flattens out over time.

To add to Whathisname's excellent post (and thank you for pointing out the important fact I ignored in my pleasure at my own rant, that one shouldn't ge hung up on specific distro information--though again, with the BSDs, most of the time, one just had to use the man pages, or perhaps the docs on the website, regardless of whether it was Open, Free, or Net, but I digress...)

As for the Negus books, one can often buy one that covers say, Fedora 9 or 10 at a VERY low price, for example, less than $1.00 US plus about $4-5 USD shipping, that will be current--the Negus books tend to be for RH version X and Fedora Y--but Fedora updates every 6 months or so--so, someone might be selling a Fedora 12 or 13 book, which will also cover RHEL6 (I think), for a VERY low price.

As my 2cents i would like to point out The Linux Documentation Project and it's web site tldp.org
As I am not much more than a newbie to Linux I cannot really say whether the site will be of any use to you especially. However,
I feel it is worth mentioning at least (once) in this thread as a general resource. There is also (some) CentOS / Red Hat -specific stuff.

Welcome to the CentOS fora. Please see the recommended reading for new users linked in my signature.

TLDP is quite good for general Linux information, but tends to be a bit dated, and by intent not distro-specific.

This is really the issue of Linux in general, since most of it runs using CLI you need a lot of very detailed documentation, because selecting an option isn't that simple. This all can be solved with a good GUI that would be intuitive.

Feel free to create one. That's what open source is all about.

A non-trivial task in an imperfect world.