----- Original Message ----- From: SJ Black <alphafemale@radiant.net> To: Jack Barnett <jbarnett@axil.netmate.com> Sent: Friday, February 18, 2000 11:29 AM Subject: Re: [SLE] mind if I vomit?
Jack -
Sorry, I should have qualified the word 'documentation' with decent, good, or high-quality. There is, admittedly TONS of dicumentation, but quantity is NO substitute for quality.
The LDP is a case in point, as rating only second-worst to the infernal man pages. I don't know what the translations of the LDP or manpages are like, but the English ones, in short, suck. They are, to new users, complete gibberish.
Man pages for example are not intended to teach new users the concepts about the commands and how to use them properly, the man pages are an online guide for when you forget the parameters of a command. For example, the man page for dump isn't going to explain why you should back up and go into discussion about how offen a system needs to be backuped up. It isn't going to explain why it is good to rotate tapes. This is stuff that new to backup learn first. The man pages for dump or for people who already know this information, it is for the people who know the terms and concepts but don't know, or forgot what parameter lets you use a differant tape drive then the default. When you need a quick answer on how to go into interactive mode on dump, the man page for this is price less. `man dump` 30 seconds later the backup is going on it's way and you didn't have to run and find you "O'Reilly Back up and Restore" hunt though the index then hunt though the 300 pages to find a simple parameter. The howto's give more pointers than anything. It is a road map. It is a series of small things to do in this order to achieve this goal. Then you look at each small thing listed in the howto and even though the howto might not directly address howto setup apache for example, but there is another howto that explains just that, plus there is a FAQ and install docs at http://www.apache.org. So even if the orignal howto that simple said "Make sure you httpd is properly setup before you install mySQL" it might not directly go into detail about setting up the httpd, but there is other documents that do nothing but explain howto compile, install and configure the httpd properly. When ever I try to do something new with the system, I always reading allot more docs than what was "Suggested". For example, today I am install openssh (http://www.openssh.org). I readed the INSTALL doc, tried to install it, didn't work. I re-readed the install doc and see that it required zlib and openssl. I read the doc on howto install zlib, installed zlib. I read the doc on openssl, installed openssl. Install of openssh worked perfect, nowI am reading the docs on sshd and ssh on how to configure them properly. True, the doc in the openssh.tar.gz called INSTALL didn't clearly explain howto install openssh step by step. But if you read the zlib doc, then the openssl doc then the openssl doc in that order, it is a step by step clearly explained on howto install openssh from start to finish. Even though these docs are not written by the same authors, it walks you step by step though the entire process. There isn't a well written book that explain howto compile, install, configure and use openssh, but if you read all the docs avaiable, all the information is there. Hell I had to goto the commerical ssh site to get information about Win32 ssh/telnet clients avaiable. Just because it isn't package in a step by step book, doesn't mean it isn't there. As far as quality goes, most documents for programs, and written by the people who know the program the best, the author. Try getting a book on OutLook Express written by the head programmer of OutLook Ex. All these differant type of documents have there differant uses. I don't know anyone who learned about clustering from just reading man pages. I also don't know anyone who setup virtual hosting with reading nothing but the howto on it and never even glance at the ifconfig man page. Use them other.
At one point, *i* needed a translator. I'm a coder. English is my first language. 8)
When you come across a word you don't know do this man fluxcaber man -k fluxcaber info fluxcaber fluxcaber --help wget http://sdb.suse.de/cgi-bin/sdbsearch_en.cgi?stichwort=fluxcabi zgrep -i fluxcaber /usr/doc/howto/* | more elm -s "What the hell is a fluxcaber?" suse-linux-e-help@suse.com < /dev/null Bitchx /join #linuxhelp what is a fluxcaber? Everyone comes across a word that they don't know, or a sentance that makes no sense what so ever, check other docs and see how it is used, if you can't firgure it out from there email the list, someone here will know. After you understand what it means, go back and read some more. Sit me in front of a C++ or ASM book and it takes me 2-3 days just to get though a page or so, it doesn't mean it is a bad book it just means I am not comfortable with code speak. Once I learn the terms, words and phases these programmers use I will be able to understand the book better and overtime I am willing to bet I can even learn some C++ from "Practical C & C++" if I take the time to learn the jive these cool cats use in programing land.
I didn't say there was no documentation. But what's there isn't great.
OTOH,
OTOH?
i have wanted to send thank you letters with kisses all over them to O'Reilly and Associates...
Alpha
They make great books on Linux and freinds, just stick with them they have allot of it, and they are real high quality books. What did you need to learn that ORA can't teach? Even Linux documents are difficult, try going to an OS where they isn't any documents, like IRIX. Go over to OpenBSD they have a FAQ, install guide, man pages and 1 book dealing with the OS. Sure they are great docs, but how much information can you put in 1 FAQ? Even though it is a great OS it is difficult to understand without enough information to walk one though the entire process. Even with good docs I am not saying that it is easy to learn, just more helpful. -- To unsubscribe send e-mail to suse-linux-e-unsubscribe@suse.com For additional commands send e-mail to suse-linux-e-help@suse.com Also check the FAQ at http://www.suse.com/Support/Doku/FAQ/