user manuals

[Randicus]

I have noticed a problem with Fedora's documentation. There is lots of useless information, such as how to change the desktop background (I figured it out immediately with no Linux experience.) and how to play a video (Such programmes are self-explanatory). However, finding useful information, such as a sudo guide, are harder to find. This kind of information should be in the documentation right after the help for people who cannot figure out how to log in, not hidden as esoteric knowledge. Although the fora have many kind people willing to share their knowledge and experience, (Which is greatly appreciated by the way.) it should be necessary to resort to a forum in order to find instructions on how to use applications.
At least, that is my opinion.
I mention this, because I am at that ackward stage where I am neither a beginner nor an expert. The problem is not a Ferora problem. Most, if not all distributions, do the same thing. Guilds are either for people who need instructions on how to use a spoon or for people who can use the terminal in their sleep. For those of use in middle, beginner guilds are useless and expert guilds are above our heads. It would be nice if someone were to put together a guild that explained more advanced procedures without assuming the reader is a power user.
Obviously, I cannot write such a manual. I am still lost when trying to use the terminal.

[Dangermouse]

Have you checked out Fedora Set-Up Guides (http://www.fedoraforum.org/?view=fedora_setup) ????????????

[Randicus]

Yes, I already have autoten. The other two links are better than the documentation on the home page, but only a little better. What I am looking for are manuals to learn how to use applications like sudo, yum and nautilus. Every guild I have seen gives precise details on how to set up an application, but then says use commands like ... Is there a source that provides a list of basic commands for such applications and the terminal? If there is not, there should be.

[bob]

And, how about the "man" pages? Open a terminal and type "man sudo" for instance. "man yum" and so forth. Lots of info there.

[RHamel]

If you also click on release notes there is a lot documentation there.

[Randicus]

The release notes are what I was referring too. Very basic. This is how too turn on your computer.
I might try the man pages though but later. Right now I am experiencing bug that will probably require re-installing.

[glennzo]

SUDO: http://www.gratisoft.us/sudo/man/1.8.0/sudo.man.html
YUM: http://yum.baseurl.org/ http://fedoraproject.org/wiki/Tools/yum http://www.centos.org/docs/5/html/yum/
NAUTILUS: http://live.gnome.org/Nautilus

Google

[Mariusz W]

Although the fora have many kind people willing to share their knowledge and experience, (Which is greatly appreciated by the way.) it should be necessary to resort to a forum in order to find instructions on how to use applications.
At least, that is my opinion.

It is not necessary to resort to fora with such questions. You must be still pretty much a novice to UNIX/Linux operating systems not to be aware that there are literally zillions of pages, both online and in printed form, devoted to Linux and Linux commands, and at least two dozen introductory Linux books.

Find the one that suits you, print it out or buy it—it will certainly be worth it, and it will teach you a lot, and you will be using it and learning from it for months and years. Always do your homework first before coming with your questions to the forum.

[Dan]

It would be nice if someone were to put together a guide that explained more advanced procedures without assuming the reader is a power user.
Obviously, I cannot write such a manual. I am still lost when trying to use the terminal. The first sentence here is accurate, but the second is a cop-out, and the third sounds like an excuse.

This is a community developed distro. If you've got the fire in the belly, and the ability to do so, you are both free and encouraged to join the documentation group at the project and put some finger whipping/shoe leather to the problem.

[smr54]

Linux documentation is horrible, simple as that.


To make it worse, if you complain about it, as you see, it turns out there are places where it exists, scattered all over the Internet, then it's your fault for not finding it. :)

ArchLinux and the BSDs (and MS) tend to have good centralized documentation. The BSD man pages are also often, though not always, clearer than the Linux versions, giving examples of usage.

Official Fedora/RH docs, especially RH, are usually not all that good at realizing what the beginner needs to know.

Another good source might be Amazon. The Negus books for the older editions of Fedora are usually available used for a few dollars plus shipping--for example, Fedora 12, and for the novice, will cover most of the things you'll need to know.

Otherwise, the best thing to do, cliche though it may be, is google for what you need to know, and possibly add the word tutorial to your search. In almost all cases, you'll find that someone has a written an easy to follow guide. I don't know of any centralized one though.

Oddly enough, though you think you're not the one to do it, you might just be the one. Why? Because YOU will know what the beginner needs, more than the expert will know. For example, having done certain things for so long, I might forget that just saying to someone, Decompress and untar the tarball, isn't really a self-standing instruction, whereas the beginner will realize that someone has to be given a step by step instruction, along with, perhaps, a definition of untar.

[CronoCloud]

I mention this, because I am at that ackward stage where I am neither a beginner nor an expert.

Ahhhh, that stage. I'm there too, it can last for a loooong time. (Yes, yes I've been using linux for 9 years but I'm no expert)

It would be nice if someone were to put together a guild that explained more advanced procedures without assuming the reader is a power user.

Why yes, that would be nice.

Obviously, I cannot write such a manual.

Are you sure about that? Even simple HOWTO's can come in handy.

I am still lost when trying to use the terminal.

It's not that hard to do simple things in it.

And, how about the "man" pages? Open a terminal and type "man sudo" for instance. "man yum" and so forth. Lots of info there.

The polite version of the classic RTFM! That would be a good idea, but many man pages, to put it bluntly, suck.

It is not necessary to resort to fora with such questions. You must be still pretty much a novice to UNIX/Linux operating systems not to be aware that there are literally zillions of pages, both online and in printed form, devoted to Linux and Linux commands, and at least two dozen introductory Linux books.

And that is the classic "google is the help desk" response. Yes, Google has saved my Linux butt now and then, but sometimes it's hard to find what you need, and what actually works and what isn't out of date.

Find the one that suits you, print it out or buy it—it will certainly be worth it, and it will teach you a lot, and you will be using it and learning from it for months and years.

I heartily recommend a good basic FAT Linux book. When I first started with Linux, they helped...a lot. Just picked up a copy of Mark Sobell's "A Practical Guide to Fedora and Red Hat Enterprise Linux" for $5 at Borders. Sure it's F12 based but but F14 isn't all that different, and the basic info about the terminal and other things would be useful for many years.
[/QUOTE]

The first sentence here is accurate, but the second is a cop-out, and the third sounds like an excuse.

I don't think it's entirely a cop out. For example I once complained about how the pidgin documenation sucked when i was trying to figure out how to do something, and somebody in the pidgin IRC channel, said yes, that the documentation needed work and made the slightly smart aleck comment that "I had the source so I could write better docs." to Scratch the itch myself.

Of course, that response to me was also a cop out. Because, sure, I have the source, but unless one is a programmer, it's gibberish. So I couldn't use the source to figure out what the features actually did and how to use them. The only people who knew how everything worked and what it did was the people who coded it in the first place.

This is a community developed distro. If you've got the fire in the belly, and the ability to do so, you are both free and encouraged to join the documentation group at the project and put some finger whipping/shoe leather to the problem.

While that is a good idea, we all know that good end-user documentation is a usually low priority in the open source world.

Linux documentation is horrible, simple as that.

Yes it is, but not all of it, just most of it.


To make it worse, if you complain about it, as you see, it turns out there are places where it exists, scattered all over the Internet, then it's your fault for not finding it. :)

And of course you're given the documenation version of the classic open source "fix it yourself" response.

The BSD man pages are also often, though not always, clearer than the Linux versions, giving examples of usage.

Yeah, examples, they need more examples.

Official Fedora/RH docs, especially RH, are usually not all that good at realizing what the beginner needs to know.

They're actually not that bad, really. At least the User Guide is usable.

Another good source might be Amazon. The Negus books for the older editions of Fedora are usually available used for a few dollars plus shipping--for example, Fedora 12, and for the novice, will cover most of the things you'll need to know.

Again, books help. Though I think O'Reilly needs to take a different more end-user friendly approach to "Running Linux".

Otherwise, the best thing to do, cliche though it may be, is google for what you need to know, and possibly add the word tutorial to your search. In almost all cases, you'll find that someone has a written an easy to follow guide. I don't know of any centralized one though.

And don't ignore google results for forums for other distros...sure solutions might be sometimes different, but they can point one in the right direction.

Oddly enough, though you think you're not the one to do it, you might just be the one. Why? Because YOU will know what the beginner needs, more than the expert will know.

Very insightful

For example, having done certain things for so long, I might forget that just saying to someone, Decompress and untar the tarball, isn't really a self-standing instruction, whereas the beginner will realize that someone has to be given a step by step instruction, along with, perhaps, a definition of untar.

Yes, I often use "shortcuts" in responses to questions and don't go into as much detail as I probably ought to do. For example, I don't tell people to become root before doing "yum install foo" because I've been using Linux for long enough to think, subconsciously anyway, that any dumb bunny knows to use su -l or sudo before any system administration task (like installing software)

And that...is a bad thing.

CronoCloud (Ron Rogers Jr.)

[flyingfsck]

When I refer someone to a man page, it is because that man page is the best source of information on that topic. For example, the rsync man page, the iptables man page or the swapon man page. So don't reject man pages just because you tried to read one bad one, or because someone else told you 'man pages suck'. It is really annoying when I try to help someone and that person refuses to read the man page and asks another question that is answered in the man page.

You should also look at The Linux Documentation Project at http://tldp.org

[CronoCloud]

So don't reject man pages just because you tried to read one bad one, or because someone else told you 'man pages suck'.

There are many bad ones and no one had to tell me they suck, I've been using Linux for 9 years.

It is really annoying when I try to help someone and that person refuses to read the man page and asks another question that is answered in the man page.

Can you blame them when many man pages suck? Or worse, refer you to a gnu info page.

You should also look at The Linux Documentation Project at http://tldp.org

Can't believe you're using TLDP as an example of good documentation...it's a collection of some of the most outdated info out there. I'd never point a new user there. Some of those HOWTO's are seriously out of date...check the listing of HOWTO's by modification date.

Ron Rogers Jr. (CronoCloud)

[smr54]

Sorry flyingfsck (may I call you flying?), but I'm with Ron here. Some man pages are adequate. My statement, when I tell someone to see a man page is usually something like, I think it's pretty clear, but if you run into things that aren't clear, post again.

As for the tldap, they have a few good things, but many that are also (remember, the OP is talking about the beginner) poorly written, and/or outdated pages. Though, I must say, their LVM page is still quite useful.


There are some good Linux man pages, but, especially if you come to Linux from the BSDs, you can see the difference, and most folks I know in sysadmin work consider Linux to generally have the lowest quality of man pages of the Unix and Unix-like systems.

On the other hand, yes, when you suggest that someone read something--be it a man page or a link that you googled from them, and their next question indicates they haven't bothered, that can be frustrating

[Randicus]

A few of the responses idicate that I did not make my suggestion clear. And yes, my original post was meant as a suggestion, not a complaint. My suggestion is to put the more detailed manuals in the release notes section after the basic ones. They would be easy to find. A few of the responses miss the point.
"...it turns out there are places where it exists, scattered all over the Internet, then it's your fault for not finding it." This proves my point, not refutes it. Thank you glennzo for the links, but here is an illustration of the problems associated with searching:
http://live.gnome.org/Nautilus
I tried searching for nautilus. Nautilus, nautilus linux, etc. turns up nothing. If gnome.org is the best place to go, and Fedora uses nautilus, then an easy-to-find link would perhaps be a good idea. For example, typing a search for nautilus says go to gnome.com.
SUDO: http://www.gratisoft.us/sudo/man/1.8.0/sudo.man.html
Good luck with an internet search. I have not tried searching for sudo, but I am sure I know what result would be. Not this.

As for buying books; yes, a great idea, but not easy. I live in China. Take a guess how easy it is to find any books about Linux here, let alone ones not written in Chinese. My Chinese is not adequate enough to read technical manuals. Downloading free books may be an alternative, but I am to busy trying to configure my new system (or systems, since I have been trying more than one) to search for good free books.

I used Ubuntu for three years, but never participated in forum discussions, because of rants chastising people for suggesting changes or questioning the way something is.

CronoCloud, your reply is well-worded.:cool:

[bob]

Sadly, linux is "free" as in hardly anyone's getting paid for their contributions and what you're asking for would take a LOT of free time for people who are at or near expert level.

Many (and I do mean MANY) years ago, I was a tech writer for a number of large industrial companies and, among other things, was responsible for producing instruction manuals on the products. The engineers could create marvels but had no interest in explaining to the user how it should or would work. They also couldn't write. That was then, this is now. I wonder how much has changed.

So, while your request is lovely and possibly needed, it's asking a lot. Red Hat, Microsoft and Apple probably have talented people on their payroll, but their product is making big bucks! We have volunteers.....

[Randicus]

I checked out http://live.gnome.org/Nautilus. This is exactly what Iam referring to. Everything in this manual is stuff I figured out on my own by reading the menus. Many options are self-explanatory and the rest can be discovered through experimentation. There is no need for such manuals. The reason I was trying to learn more about nautilus, is because with other distributions, like Debian and Ubuntu, it has a very useful command: alt+F2, gksu nautilus. It lets a person access folders as root. Very easy, but Fedora works differently.
On the other hand, http://www.gratisoft.us/sudo/man/1.8.0/sudo.man.html appears to be a good manual. I only gave it a cursory look and and copied it, but from what I saw it looks good. Thanks again glennzo for the link.

[pete_1967]

And since no one has mentioned it, here goes again: http://rute.2038bug.com/index.html.gz It's old but still very, very good resource.
Another rather good source is http://linux.byexamples.com/
And the third is http://www.shell-fu.org/ for all kind of handy snippets.
Also GNU Manuals cover a lot: http://www.gnu.org/manual/manual.html

I've never found Red Hat's documentation lacking either and Fedora's manuals are getting better and better all the time.

[Mariusz W]

I tried searching for nautilus. Nautilus, nautilus linux, etc. turns up nothing.

Strive to make internet searching for information more effective: it is obvious that searching just "nautilus" will produce tons of irrelevant hits, isn't it? "Nautilus" and "linux" is better yet still quite random. Nautilus you are interested in is a file manager, so try searching, e.g., for:

nautilus file manager

I just did that and every single hit on the first page was very much relevant.

As for buying books; yes, a great idea, but not easy. I live in China. Take a guess how easy it is to find any books about Linux here, let alone ones not written in Chinese.

I don't know where do you live -- a rural area or a large town, my guess however is that it would be fairly easy: there are plenty of books on Linux available, e.g., in nearly every European language, and available from bookstores even in moderately sized towns -- I travel a lot throughout the world, I know this from personal experience.

My Chinese is not adequate enough to read technical manuals. (...)
Downloading free books may be an alternative, but I am to busy trying to configure my new system (or systems, since I have been trying more than one) to search for good free books.

I take this to mean that you live in China but your command of Chinese is not adequate. Don't you think your situation is VERY SPECIAL then? Instead of realizing that it is your own individual situation that limits your possibilities, and that it puts added responsibility on your own shoulders, you start a thread blaming your inability to find references to Linux commands on Fedora and the Linux community at large. Instead, you say you "are too busy" to "search for good free books".

It is not that "downloading free books may be an alternative" -- it is an alternative.

Knowledge costs. Always did. Always will. And I don't mean money. It primarily costs and demands great sustained effort -- on your part. If you are "too busy" for such an effort, if you are too passive, then is there any reason anybody should be expending his own efforts towards helping you?

[smr54]

Errm, yeah, I was agreeing with you. Sorry if it wasn't clear. I thought that it was clear that my post agreed with your point.

[flyingfsck]

The first thing that you have to learn when you are new to Linux is that Google has a special search engine just for Linux:
http://www.google.com/linux

It even shows a cute little penguin.

If you search for nautilus that way, ALL the links are relevant:
http://www.google.com/linux?hl=en&q=nautilus&btnG=Search

I find it hard to believe that you have been using Linux for several years and did not know that. No wonder that you are frustrated!

[stevea]

To expand on f'fsck nice post ...

hjttp://www.google.com/linux
http://tldp.org
man XXXX
info XXXX
/usr/share/doc/$PACKAGENAME
in the kernel source tree at linux..../Documentation
yelp


===========

The OP does have a point. Unlike commercial OSes there is little formal documentation and to the extent it exists it is poorly organized and in many different formats, different access methods. It's one of the reasons why google is your friend. Many times inserting en exact error message into results in an immediate explanation and solution.

What are they ???

We all understand google. If you don't know - start at google.com/linux.

"http://tldp.org" a long standing project filled with a wonderful collection of detaile descrptions and howtos. Often ot of dat, and constantly in revision. I good place to check, but not a one-stop solution. There are other websites, like http://www.linuxhomenetworking.com/, that also contain loads of howtos on specific topics.

The venerable ancient "man" command was a innovative in the early 1980s. The nroff, troff file format is a relic of an earlier age when commercial printers were a lot less capable than a $50 Lexmark. Sadly this turgid old format is the main documatation for syscalls, basic libraries, some language specific libraries and most command line tools.

'Info' was designed by the GNU project to expand on and possibly replace 'man' It's still text oriented, but includes a very emacs-ish form of text hyperlinks. This tool give considerably more detailed descriptions of the use of SOME command line tools. No one is seriously advancing this format any longer however some of the documentation in this form is irreplaceable.

There used to be an X oriented 'Xman' in the basic Xtools, it's now moved to the "neXtaw" package. This command was able to access the 'man' output and display it nicely in a window -. Not clever or smart, but a good tool gone missing.

/usr/share/doc/* is a terrific resource. For each installed package (with exceptions there is a subdirectory - however the contents can be anything from amazing to nil. The formats are random. So to understand ntp or pam try ...
firefox /usr/share/doc/ntp-4.2.6p3/html/index.html
firefox /usr/share/doc/pam-1.1.1/html/Linux-PAM_SAG.html
You'll find other odds & ends - from changelogs to sample code to text files in these directories.

If you need to understand how a kernel feature works you need to look under the linux.../Document directory. Or it's webish equivalent.
http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=tree;f=Documentation;h=e5883198278cd5f05 3188f68c35bfb453453098a;hb=HEAD
Usually reasonably up to date, but there is some old cruft in there.

yelp (same as 'gnome-help'). I nice little tool that is strictly gnome-centric. It displays indexed and hyper-linked descriptions of gnome tools. Sadly the content is ALWAYS horribly out of date and only a minority of gnomish commands and topics are covered.

[DBelton]

One thing you may want to check out.

If it is a GUI program you are looking for more information on, try hitting F1. A lot of them have help built into them (or like firefox, sends you to their help webpage)