“What makes GNU/Linux such a pleasure to use is the excellent documentation that is included with it for each and every tool bundled with it. Just try learning to use iptables without reading the documentation even once, and you will get the idea. The documentation in Linux is available in a variety of formats – as man pages, info, HTML pages, postscript and in some cases even pdf. But not many people are aware that you can have additional documentation and even whole books available locally for making your GNU/Linux experience that much richer. Here are a few of them that have come to my notice.”
What makes GNU/Linux such a pleasure to use is the excellent documentation
Is this a joke? It’s a real jungle…
You beat me to it. Documentation for Linux is hit or miss and it’s hard to find good documentation all in one place like you can get from Microsoft (the MSDN library is generally pretty good).
Doesn’t get much better than free books. Everything in Linux is extremely well documented, may not rub your nose in it when you hit F1 but it’s there, available and gets a little better every day.
So where is all this great documentation? I head over to Linuxdocs.org, and I see HowTos that haven’t been updated since 1997. How is one to tell whether something is actually up to date or not?
I head over to Linuxdocs.org, and I see HowTos that haven’t been updated since 1997.
Actually, linuxdocs.org is the old site. The new site is tldp.org. Which stands for The Linux Documentation Project. As far as the claim that Linux has an excellent set of documentation – I second that. The only problem is that people in general are a lazy lot. Just can’t pull oneself to open up the man page and read the docs.
The problem is with the people and not with linux
I agree with you that the problem is with people not with Linux _but_ only in the cases of either power-users (me, you, my boss that is a sysadmin e.t.c.) or to users with great determination and willingness to expreriment, learn e.t.c. But this kind of logic does not apply for everyday people – at least until they _do_ become powerusers. When people ask me whether they should install Linux or Windows I lower my head and advise them to get a Mac, simply because `it just works’ for the most part and certainly for a much greater part than in Linux or Windows – There is nothing bad in recognizing the truth. I can’t tell them `Hey, look. The documentation in Linux is awesome’. Cause it is awesome (yes) … but for me not for them mate.
> The problem is with the people and not with linux
However, nothing prevented people of, for example, FreeBSD community to create excellent man pages and update them periodically, to make a lot of other very useful docs located at /usr/share/doc, /usr/share/examples of FreeBSD installation.
Whoa, there! I’m certainly no lazy user, but I’ve run in to dozens of programs- CLI and GUI- where the documentation was pittiful. There are a few things that are well documented. Someone mentioned Perl, for example. There are a lot of things that have decent documentation. But a lot of other things either have bad documentation, or the thing is so convoluted by design that no amount of documentation helps!
> The problem is with the people and not with linux
I think you should read up what usability means.
– Morin
“The problem is with the people and not with linux
”
Hmfp. The problem with saying things like that (and I’m assuming a certain level of irony in there!) is the saying “Linux is ready for the Desktop”.
FTFA:
——
Note: In each of the cases below, I have given the package name (in bold and blue color) and you have to first install them using the apt-get command if you are using Debian Linux, which means you run the command:
# apt-get install >package name<
——
I inverted the angle brackets arounf package name in order to dodge the HTML tag restrictions.
> The only problem is that people in general are a lazy lot.
Yeah, people tend to be lazy, but I still think siride is right on: it’s hit-or-miss.
On the “hit” side, for example, the Perl docs. I’m a Python guy these days, but I gotta say that the perl docs are really top-of-the-line. They contain not only well-written and correct info, but they include examples and tutorials too.
GNU docs tend to be pretty good, as RMS considers incorrect docs as bugs to be fixed.
The Apache docs are pretty good. There’s a funny dynamic there actually. The folks who license their software BSD-style in general tend to just want you to use it, regardless whether you give back. To that end, I think they usually work hard at having good docs, since that’s what will get them more users.
Regarding the phrase, “for offline use” — of course, for many of the online docs, hopefully they provide a downloadable version too, so it’s just: download it to your ~/docs_others directory, unpack it, bookmark it, and it’s now available for offline use.
With more and more projects using wiki’s for their docs, a nice feature of any wiki might be to have an easy way to download an archive containing a snapshot of the current wiki, such that you could reconstitute it on your own machine.
RedHat and Novell both have excellent online documentation too.
see:
http://www.redhat.com/docs/
http://www.novell.com/documentation/suse10/index.html
Along the same lines, Gentoo’s documents tend to be excellent as well, albeit tailored well to the “Gentoo way.”
When it comes to buying books there are indeed a number of good ones out there. But as far as the free documentation that comes with GNU/Linux the range of docs range for docs is from “Made in Heaven” to “Hitting my head against the wall is less painful”.
If GNU/Linux docs are so clear, point me to a set of docs for “setserial” that can be read by a normal human being. It turned out easyier for me to write an entire program from byte one than to follow the instructions for that monster.
My biggest problem with most man pages is that they typically don’t provide any examples of common commands along with explanations of what they do. This simple thing would increase the usability of the documentation immeasurably.
Including a few sample commands would turn a man page into a mini-howto.
The other documentation problem is that many of the included tools are too complex and interdependant for a single document with a limited scope to adequately describe.
The complexity of the tools is not going to change, “fixing” that would break too many other things. B^)
A well-written overview of networking (for instance) in *nix and the related commands would tremendously help a newbie who is trying to complete a task.
Who said great comedy http://commentgator.blogspot.com/2006/02/who-said-comedy-was-dead.h… ?
My biggest problem with most man pages is that they typically don’t provide any examples of common commands along with explanations of what they do. This simple thing would increase the usability of the documentation immeasurably.
Bingo on that point. Right on the money.