typodupeerror
• #### too much documentation (Score:1)

Part of the problem is there is too much documentation. Just reading the documentation sequentially would take ages. It's not all that well indexed, and much of it assumes certain prior knowledge. Much of it is self recursive in prerequisite.

Linux newsbies come in 2 popular flavors: those already experienced with computers (mostly Windows or Mac, but even some UNIX), and those without any computer experience. Those with experience are the largest group right now. And many are actually deploying, or soon will be deploying, Linux (or one of the BSD cousins).

Many newsbies want, and need, to learn fast. And that means not spending the time to learn everything else whether it is actually needed or not. While it's always good to learn the foundations, it's often not practical for many newbies because they are entering the Linux realm because of a need to solve some technical problem in their new deployment today (probably brought on by not having spent the last 3 months reading every document).

I've watched the questions newbies ask. Sure, a few are "where can I learn all about Linux?". But most are more practical like "why am I only getting half my harddrive?". These questions are the result of someone actually setting up, administering, or programming, Linux. They can't just drop all and go read the foundational documents because they have to get things done and running now.

Those with experience also find the introductory documentation, and beginner books, boring and dull. While there is information in there they need to know, it is surrounded more and more with stuff that is totally boring.

So, sure, we need more documentation, and we need less, at the same time. The reader paradigm is shifting from what it was just 2 or 3 years ago.

Those of us with solid Linux eperience need well referenced and indexed documentation. Some of that exists now, but it remains skimpy in many areas, and not well integrated.

Those of us with other UNIX computer experience need to know what's different about Linux, as well as the same. It will be hard reading because most of the differences are the subtle details and the abstract concepts. Many of the differences don't matter today, but they might tomorrow.

Those of us with other OS computer experience need to understand what this is all about, in 25 words or fewer, in terms of how things were done in Windows or Mac or VMS or MVS/390 or whatever it might be (anyone here still using TOPS-10/20?).

Basically the answer is that the documentation needs to be right-sized and customized. Short (read in 30 minutes or less) documents introducing Linux, oriented to each incoming experience, would be among the most needed. A solid (by that I mean well organized for looking things up) reference document is also needed for everyone once they have the Linux experience (no one can know it all anymore, especially with so many distributions and other diversity). Make liberal use of hyperlinks for all concepts, too.

FAQs are OK for the most common questions. But they just can't handle the mass of knowledge that really needs to be presented. While I wouldn't say to drop FAQs, as they are still a valuable tool, other documentation should not assume that FAQs are present.

I'd also like to put much blame on the horrible architecture we call the PC. But that is best left for another thread another day.
• #### Re:Newbies and documentation? Useless. (Score:1)

by Anonymous Coward
Sometimes TFM assumes knowledge that newbies don't have. I just started writing shell scripts (something I have never tried yet)on my Linux box and I was having trouble getting it to do what I want. I posted a question, got a script with explinations back. Problem is I didn't have the basic understanding so this script and explination wasn't helpful. I have figured out some but it is kinda like re-inventing the wheel myself so I can use the plans for the new Corvette.
• #### Re:Concept Mappings (Score:1)

There is a Win-to-Linux HOWTO available, AIR. It kind of went through exactly what you were stating. Basics, like 'mounting' and the like.

As for your conclusion, that a lot of people pick up a distro (Mandrake or RedHat, most likely), and bail when they hit a snag, I think you hit the nail on the head. A lot of these poeple are probably technically savvy enough to use Linux, but could sure use a hand getting things going. I know I'm one.

• #### Recent Newbees Must Document (Score:1)

Techies are great at being techie, but newbees know what they stumbled over. A Howto written by a newbee is of far greater value to other newbees because their thinking is usually decidedly non-technical. It stands to reason therefore that a non-technical newbee who has accomplished some task can explain what they did in a way that is understandable to other newbees.

Vocabulary is one of the highest hurdles that a newcomer must clear. Let the newbees write so other newbees can understand.
• #### "Point man"? (Score:2)

Nope. Just someone who meets three criteria for finding you amusing:

1) CS major, Philosophy minor so I'm familiar with logic and, in your case, illogic.
2) Liking to keep a browser open while I work.

3) Working on a large project with a long compile-time--leaving me plenty of time to respond.

So, tell me again why I should follow YOUR advice rather than RMS's. Also, could you tell me exactly what actions I have taken that are in "lock step" with RMS?
---
• #### It's not the documentation... (Score:1)

It's not the lack of documentation, but what has to be done to configure a linux box. Alot of the documentation is old and many tasks still have to be done from a command line. Documentation is pointless at that point because the typical users is going to toss it right out the window the minute he/she discovers they have to go in and do some typing. Everyone has their favorite input method, be it GUI or CLI. For those of you who argue that CLI is better, you may be right, but by no means are millions of windows-bred users going to use command line tools EVEN IF it is more intuitive. The only hope is in standard GUI based configuration utilities... and I mean STANDARD because now each distribution stubbornly chooses to do it their own way. Theres Linuxconf, YaST, Coas, the list goes on and on. It's pretty frustrating for a new linux user when he goes out and buys a book and the books prefferred configuration tools don't apply to the distro of Linux he's using.

I'm hopeful that the desktop environments (prefferably KDE but perhaps gnome) come to the rescue and provide a set of config applets that work across different distro's. Theres little hope of a Red Hat, or Caldera bending and adopting tools used in another distro.

• #### Re:Concept Mappings (Score:1)

Ever see the Dos/windows to Linux howto? It sounds about like what you are discribing...
• #### Man Pages (Score:1)

A recent event made me realize just how great the man pages are. My father was visiting for Christmas, we were in the computer room together, playing with hardware, swapping stories and playing games. He isn't new to the computer scene, but its not his life either. Until 3 years ago, he used a C64 only. Since that point, he's had a Win machine. He has reached the point that he can install Win98, and fix most of the common problems for his friends. He even builds machines himself. He's never used Linux before though, and he calls me for more in depth technical questions.

So I showed him Linux. He thought the GUI was great (kde) but when I dropped to the CLI and told him I had more power there, he looked at me and said, "If had to learn to use that, your mother would kill me. I don't have the time.".

Alright.. I could understand that, but then I pulled up a man page... Immediately he blurts out "Is that a help file??" He sounds astonished. I explain that most standard *nix applications have man pages. He was VERY impressed and started going on about how much he "wished MS would have documentation that was 1/4 that extensive and clear."

That was some good warm fuzzies for me on x-mas.

Sorry for rambling. Just thought I would share.

• #### Re:Newbies and documentation? Useless.? Nope. (Score:1)

There is two kind og newbies, the user newbies, and the tech newbies.
User newbies, yeah your argument holds, they dont RTFM. But who cares? If some techie takes the time, gets management backup, he could set up a no-questions asked windows look alike productivety workhorse.
The tech newbies are your target here. Desillioned Windows hackers. Frustrated NT Admins. They need a better Oracle server. They need it quickly, but will read the fucking manual. They will get scaredoff by compiling, so there needs to be heaps of docs here to look for.

What is usefull for tech newbies? The HOWTO's are. The FAQs are. The apps docs and man pages are. The Linux Documentation Project is. The distro docs are. Whats missing? Maybe a huge knoledge base would help.
Good helpdesk logging systems can provide lots of usefull stuff, maybe a Open Source Linux Helpdesk would be a good thing.

• #### Re:*nix needs more detailed error messages all ove (Score:1)

Sounds like perhaps we need a newbie shell? I know I wouldn't want my shell stuffed with such code. But I wouldn't want to deny it to others, either.

Now if xterm allowed hyperlinks, and you hyperlinked the error messages, then people can just click on them to get more info, that might be an interesting approach.
• #### what newbies? get rid of them (Score:1)

I was born clutching UNIX source code listing in my little hand. Never needed a manual, howto, or man page to do anything. I am UNIX. I need no stinking newbies installing linux just because it's cool. They try it, complain how hard it is, and give up. I gave up years of my life to UNIX/Linux. On irc.linux.com's #linuxhelp most questions are the same, day in and day out. The problem is, everyone wants instant answer and everyone is too lazy to RTFM. At work I get pestered so much with stupid questions about linux that I am sick of it.
• #### I never said... (Score:1)

to follow me. Think for yourself.

Ah, a college student. The great recruitment grounds for cults. Wait until you get out in the real world and realize that you can't eat following Stallman's bizzare viewpoints.

I fail to see why you being a philosophy minor means anything. I took many philosophy classes in college too, but I don't use that as a basis for arguing that I am right.

• #### A guide to writing documentation for newbies (Score:5)

<imipak@yaho[ ]om ['o.c' in gap]> on Thursday December 30, 1999 @09:02AM (#1432353) Homepage Journal
In 10 easy steps...

1. HOW-TOs need pictures. Newbies can read, but they can't necessarily relate. If they had the experience -to- relate, they wouldn't be newbies and probably wouldn't need HOW-TO's either.
2. We need MANY MORE translations. Linux is international. The documentation isn't.
3. Related to the above - the "man" command needs to support multiple languages, and the "man" documents need to be translated.
4. Installers need better "back-stepping". Not everyone has one of those globes from "7 Days". It should be possible to undo exactly one step, at ANY time.
5. There needs to be optional "automagic" configurations. One-button installation, for given categories of user, taking you right the way through with NO further interaction. The computer picks sensible partition sizes, arranges things just so, configures -everything- and installs all the packages that that category of user would want, given the size of disk, speed of processor and amount of RAM.
6. Linuxconf is good, but doesn't cover -nearly- enough areas. It needs to do MUCH more.
8. Documentation should be in hypertext format. Either "classic" hypertext, using links, or in the more mundane (but truly original) folded document style. Seeing too much can blind even an expert, never mind a newcomer.
9. X configuration is -still- the worst part. This MUST be made more automatic, with automatic graphic card detection & identification as far as humanly possible.
10. PPP is not as friendly as it could be. I've lost count of the number of times either PPP, chat, or one of the GUI tools, has barfed, with no error message, no core dump, no message in the log and no information as to even that there's a problem other than ifconfig shows PPP isn't there and 'ps axuw | grep pppd' returns a big, fat zilch.
11. For "newbies" who are at the point of wanting to do kernel upgrades, there needs to be a script which sets the defaults to intelligent values. I mean, let's face it. If you're running a 386, it doesn't make any sense for the Linux kernel menuconfig script to start by assuming you want to work on a Pentium II. Sure, you might, but doesn't it seem likely that you are more likely to want a kernel on the system you're using? Once you tell it, sure, it can retain the value for next time, but initially, sensible values would seem sane.
12. The same goes for everything else. Sensible Defaults, PLEASE!!

(Ok, so I lied about it being 10... :)

• #### My Experience as a Linux newbie (Score:2)

My Experience as a Linux newbie and what I desired most as a Linux
Newbie...

Though linux was new to me UNIX wasn't. So didn't have to understand
how linux system works in general. I didn't have many of those
questions that are faced by my other friends who started to use or
experiment with linux and had no prior *NIX experience.

I didn't know how to configure my sound card, how to use TrueType
fonts, how to use jdk1.1.7 with StarOffice, How to configure my
network card which the RedHat install program failed to detect, how to
use my CD-RW drive with linux machine. It took me some time to solve
the mystery of winmodems.

Almost always I could find answers to my questions on either HOWTO,
Deja, LinuxStart, tunelinux or irc.linux.com #linuxhelp. Because my
problems were trivial people on linux related IRC channles didn't show
any interest in solving my problems. They most of the times just used
to ignore me, or tell me to RTFM... but my problem was I even didn't
know which program I'm supposed to use to solve the problem so how
would I know which man page to read? May be the questions I was asking
were silly, but I even didn't know that they were silly.

But I could always solve the problems with one of the popular Linux
website's help. I was willing to take efforts and knew where to
look. I wonder how many new Linux users do that. Particularly if s/he
was a windows user in past. Linux HOWTOs are a great help. Websites
like justlinux.com, tunelinux.com, Deja, linuxstart.com do a good job.

Sometimes I was overwhelmed by the amount of information available
about a subject. It took time to filter through all that information

It is best for a newbie to get in touch with some local Linux guru and
learn from him/her. Every linux enthusiast can contribute some of his
time to local Linux user group and help new linux users learn more.
• #### Re:Newbies and documentation? Useless. (Score:1)

Take a look at The Dos to Linux HOWTO [linux.com]

It should be what you're looking for.

I know that there is already a Linux web ring but I think that a centralized place (like linux.org) that has things broken down into subjects with links to specific sites that specialize in one area. I have been using Linux for 2 years now and I have yet to see a site like this. I think that linuxstart.com and linux.com have the right idea but each a little ways off. Then if someone could print out a book that highlights the most used areas of that site could: a) make a lot of money b) help a lot of newbies out c) make life a lot less crowded in the newsgroups Thats my $.02 • #### Another Linux newbie concurs (Score:2) Now, don't get me wrong, I've been on the Net since '78, helped crack games back in Apple II days, and seen more OS than I care to recall (CP/M, DOS, Unix flavors, many more). But I have to admit, especially since I've set up Mac Servers to run native Unix, configured various daemons, and so on - it is a tad bit confusing on the Linux side. It would really be nice to do a default Secure install and then enable services as I need them, without looking totally clueless as to the exact name of the script I'm supposed to have guessed at somehow. I can cope with it, especially with tons of Linux geeks amongst my friends - spent part of Trolloween talking about how to do IPV6 with another friend as we watched them light a dinosaur on fire, for example. But I think we're going to get way more confusion than usual, as all the totally clueless come wandering over from MSFT Windows1900 to find something that works. • #### Documentation format (Score:5) <ajs@ajs. c o m> on Thursday December 30, 1999 @09:05AM (#1432359) Homepage Journal The fundamental problem right now is that no one knows what format their documentation should be in, and many people just punt or write minimal documentation as a result. HTML is useless for creating any kind of structured searching (unless you layer a documentation standard on top of it). roff has a decent documentation standard for UNIX, but no one likes it any more. texinfo is nearly impossible to manage since it requires sophisticated tools that don't play nice with anything that anyone actually uses. Plus, it requires a central table of contents which is difficult to manage automatically from un/installation scripts. I've been thinking about it, and I really believe that Larry Wall's greatest contribution to the world has been POD (not Perl, itself). POD is a very simple documentation format that can be used to follow the roff-ish manual conventions of UNIX, but the format is so simple that it can be converted to man, HTML, texinfo (though texinfo standards usually want more prose than a UNIX manpage has), plain text, etc. This is a very nice solution for someone who's ambitious enough to go through the entire Linux documentation base (HOWTOs, FAQs, man pages, texinfo, PostScript, etc) and convert it all to this one format. Then each distribution could choose it's pet format to render in (probably *both* HTML for the new people and man for those who have "man -k" hardwired into their brains). It would be nice to layer a few additional features on top of POD: T which takes a term or phrase and indicates that this particular section of this document defines that term in a way that should be indexed globally. This is not quite the same as LaTeX's indexing. More of an HTML "A NAME=" sort of thing, but where HTMLs mechanism could be called a pull model, T would be a push. H which takes a semi-colon separated URL and filename. The filename is an image that should be used as a figure in the document (numbered from one on). If the URL is provided, it is the location that should be referenced when users view this document in a text-only setting. The lack of images in POD is the only thing I don't like, and I know that it's quite unreasonable to expect that all Linux users (or UNIX users in general, for that matter) will be viewing documentation under a windowing system, but it would be nice to be able to show diagrams and other figures when the possibility exists. Given these minor changes, rewriting the documentation would consist of converting all of the extant documentation over to text and then hand-hacking it back to POD (POD is very nearly plain text, with minimal markup that makes HTML look like a general purpose programming language). Any thoughts. Should I just duck now? • #### Something to tell them how to solve their problems (Score:2) i agree, there is a bit of a dearth of good introductory documentation for Linux. there definitely is a lot of documentation out there, a lot of it very good, and as technical as can be. the HOW-TOs have been one of the best additions in recent years - giving good guides to get things done. however, both from my own experience getting to know linux and helping others with the same, the question that crops up most commonly, for a newbie, once the lot is installed, is not "How do I do xxx" but rather "Ok, so what do I do now?" The beginning user is unfamiliar with the potential of what they can do with Linux, rather than how to do what they want. This is where I feel the documentation lacks a little. What we would need is a set of "beginner tutorials" for various tasks, kinda like meta-HOW-TOs, or WHAT-TOs, if you like :) These would familiarize the user what they can look into doing, and in the process, get them familiar with the resources they have - what the HOW-TOs are, how to look up something in the man pages, and so on and so forth. Once a user is familiar with what to look through to get an idea of what to do and how, they are usually pretty self-sufficient. A development of this sort of documentation would make entry to Linux less daunting, more friendly, and help users get on and learn the OS with more confidence. As long as we don't have a stupid paperclip or anything. Fross :) • #### Re:Dealing with New Users is easy (Score:2) Taken as a joke, that comment is pretty funny. Unfortunately, I suspect that there is more than a grain of truth in that little message. Quite honestly, it's elitist opinions like this one that will help keep Micro$oft's sorry efforts the Operating Systems of choice for the majority.

The sad fact of the matter is that the average Joe User doesn't want to have to read through reams of manuals to get their computer working. They want quick, easy, 'sound-bite' (should that be sound-byte?) help information. They want the 'Press F1 for a graphically pretty' type of help. But most of all, they don't want to be met with derision and hostility from the existing user community.

Just my thoughts...

--
• #### How about a knowledge base type thing (Score:2)

I would have loved ONE place to go like the Microsoft KB when I was trying to get my redhat going. Yes, I could go to the RH site for most of it, but I often went to a list of other bookmarks as well.
• #### Re:My Newbie HOWTO (Score:2)

RTFM, for a Linux newbie (however proficient with computers they are) is extreemly frustrating.

Linux does take a little getting used to. I finally took the plunge on my home computer two months ago, and it was a scary experience for me. It is a vastly different paradigm than DOS/Windoze. It's scary to be partitioning a secondary drive, not wanting to accidently partition your primary drive (which still has Win95 on it, along with years of beloved data), especially when the partitions have names like, "hda1" and "hdb6" instead of "C" and "E".

I'm very fortunate that some people on IRC were willing to give me a few begruding answers. RTFM doesn't help much when you're not even sure where to start looking. Even linux.org doesn't help much when you don't know an XFree86 from a \dev\...

Now that I've used it a bit and understand some of the basics, finding help in the manuals is much easier, though it can still be tiresome and frustrating.

I wouldn't mind seeing some better documentation out there. It seems to me that the HOWTO's are a bit disorganized, and in some cases didn't cover topics I needed to read about. I figured with all this open-sourceness and late-night-labor-of-love coding that there would be plenty great docs overlapping every possible known linux configuration. Yet I had a heck of a time trying to find out what an error message meant when I kept trying to use X.

I like Linux, and I'd love to see it one everyone's workstation in every business and home and send Gates back to his mommy. Most people are afraid of it, though, and good support and docs is just the thing to help abate that. Anything to help alieviate the confusion would contribute to its success.

(As a funny side-note... The guy who convinced me to install linux promptly disappeared from IRC for a month and a half, until about the time I got it running... So much for his help! :) )
• #### Re:Maybe... (Score:2)

Not every Linux user has time to help every newbie who asks a question. Some Linux users don't have time for any questions.

Me, I have time for a small set of questions, those which deal with software I use on a daily basis and can answer with minimal research. Ask me an Emacs question, and I can and will help you. Ask me how to set up PPP or your sound card, and I won't help you, because while I've done it (and do it on a semiregular basis) I don't remember enough to give someone step-by-step instructions that will always work. I don't have time to work with someone to get all the information needed to set things up.
• #### No one reads the fine manuals anymore... (Score:2)

The sad situation is that most people won't read their manuals. Proof of this can be seen by observing the millions of VCR's that steadily blink 00:00:00. Not reading manuals is human nature. To read a manual is to enter the "student" mode, and people want to stay in their "user" mode. Hackers and geeks are not normal people. We are always in the "student" mode, so reading the manual is second nature.

Not reading the manual is not confined to Linux, as we all know. I've seen quite a few people running Windows on a 20" monitor at 640x480 resolution. Or using Excel for wordprocessing because "it has columns already for me". Over Christmas, I was playing Freecell on my Aunt's computer. She was very surprised that there were games on her computer, even though she's had it for two years.

When the average person does decide that they do need to read the manual, they refuse to read it all the way through, and instead try to find that one piece of information they currently need. This stratagem never works, of course, since they have no foundation to base that information on.

However, there are a couple of simple things that can ease a newbies transition to Linux. First of all, don't ignore or flame a newbie question on the lists. Take some time out of every week to hit the lists and gently reply to newbie questions. Don't tell them to RTFM, but instead direct them to a more appropriate list if the question is off-topic. If it's already covered in the FAQ, patiently explain it all over again, then show them the FAQ.
• #### Exactly!! Newbies want context and a framework (Score:2)

Fross, you have wonderfully summed up what I was trying to say!

the question that crops up most commonly, for a newbie, once the lot is installed, is not "How do I do xxx" but rather "Ok, so what do I do now?"

That is exactly it - there is no guiding doco for beginners. After the installation, the documents perhaps could then give examples of what the user could do next with links to the relevant HOW-TO docos.

This would at least then put the HOW-TO docos in context and provide a framework which would show the users where everything fits together.

• #### how good documentation is organized (Score:3)

on Thursday December 30, 1999 @09:32AM (#1432399) Homepage
Speaking as a tech writer...

When programmers write documentation for a program or system of programs, they usually organize it according to how the program is written, or how the modules of the system interact, or the functions of the modules.

For example, the chapters of the Linux System Administrator's Guide [linuxdoc.org] seem to be organized as follows:

• Introduction/overview (chapters 1 and 2)
• Files and disks (chapters 3, 4, and 5)
• Booting, shutting down, logging in, logging out (chapters 6, 7, and 8)
• Backups (chapter 10)
• Time (chapter 11)
The Network Administrator's Guide [linuxdoc.org] goes like this:
• Introduction (preface and chapter 1)
• How TCP/IP and DNS work (chapter 2)
• Hardware configuration (chapters 3 and 4)
• Configuring Linux's implementation of the protocols (chapters 5 through 8)
• Various network applications (chapter 9)
• Services useful in a LAN (chapters 10 and 11)
• UUCP (chapter 12)
• Email (chapters 13 through 15)
• Netnews (chapters 16 through 19)

What's wrong with that approach, you may ask?

When non-programmers approach a computer system, they don't care about how it's put together; they care about doing something with it. The division of tasks that can be done with a computer system is mostly orthogonal to the division of modules in it.

For example, if you want to download mail from an ISP to a Linux box over a dial-up connection, that will involve booting the computer, logging in, executing a program that lives somewhere on my hard drive, making a PPP connection, etc., etc. The information relevant to that task is spread through the above two books. How can a newbie who wants to read mail with Linux, but doesn't want to become a Unix wizard, know where the relevant information is in those hundreds of pages -- not to mention HOWTOs and man pages? If something goes wrong, how can a newbie know where to look for the solution?
--
"But, Mulder, the new millennium doesn't begin until January 2001."

• #### Re:Tech Newbie (Score:4)

on Thursday December 30, 1999 @09:48AM (#1432417)
That attitude is whats wrong with alot of computer prefessionals and give us a bad name.

Now I'm a LINUX newbie, I've got a couple of boxes running RedHat, Caldera OpenLinux and YellowDog Linux PPC, but I'm no expert. I've read the manuals and the on-line documentation, but there is alot missing.

When I have a Windoze question, I can ask around and people are helpful. When I have a Macintosh question, I either know the answer or someone on support.apple.com will help me. But when I have a Linux question...all one gets is Read The Fletchin Manual. You know what alot of those manuals are wildly out of date. I bought a Caldera book just five monthes ago...guess what...the only Caldera book then covered 1.3...I'm running 2.3 it helps me not. So what good is RTFM when TFM is out of date?

Just the other night my ISP switched our IP numbers around, a couple of hours early. My RedHat 5.2 box hung and hung hard when I tried to fire up X...then on reboot SMB took 45 minutes to start because of the IP number problem. I didn't see that in any manual. I got lucky that someone at my ISP could walk me through using PICO to edit the config files so I could get my box back up.

If I'd have asked you, I would have just gotten burned.
• #### Re:Typical jerk response. (Score:2)

you wouldn't have learned without the help of someone along the way.

You'd be surprised. A lot of us _did_ learn Linux via available documentation at the time. When I was setting things up, I scanned the newsgroups and read all the howtos. It was rare I had to ask a question, because I could usually find where someone had asked it before, and find the answer they'd recieved.

This is not an impossible thing. Maybe it's impractical for many people, maybe it's undesirable, but it's definately possible.

• #### Re:The Problem With People who Annoy Newbies (Score:3)

on Thursday December 30, 1999 @09:55AM (#1432424) Homepage
They ask far too general questions. "How do I get on the net with Linux?". Of course, if you decide to help with this question, they'll get irritated when you start getting into the details of how things work. You see, newbies want to gloss over everything without having at least some fundamental knowledge of how things work.
If they ask you how to do something, and you respond by telling them how something works, you're not paying attention to their question. And then you complain that "newbies" don't pay attention the documentation! Sheesh.

If a newbie asks you a question, listen (or read) carefully enough to give a relevant answer. "I know how to do that, but I don't know how to teach it to you" is a relevant answer, and one which demonstrates respect for the person who asked.
--
"But, Mulder, the new millennium doesn't begin until January 2001."

• #### Linux is Free - The Manuals are not. (Score:2)

Does this really solve the problem though? Of course not, all the newbies aren't going to rush out and pick up a 50$copy of Redhat 6 or Suse because they can't find out how to do X. Instead it seems that some alternative needs to be created. In my eyes, this alternative is before it's time. The world isn't really ready for digital books yet - sure, there are a few places stacking up for the new paradigm shift. I just read an article the other day in Infoworld that discussed traditional publishing houses like Houghton Mifflen, Bertelsmann, and Macmillan teaming up with technology partners such as Xerox, Hewlett-Packard, Reciprocal, and Fatbrain.com. However Infoworld agrees with me that "until portable technology had evolved to a point that's truly comparable to the print reading experience, certain types of information will remain in print for some time." In the same report Jack Staff - chief Internet economist at Zona Research - mentioned, "A book is as fine a PDA as you'll ever find. So as long as we still have paper, binding, and so on, there will be people that want to buy books.". It looks like the technology for Neal Stephenson's "I recall RMS saying once that he disliked O'reilly because they made such good manuals that free software developers would not bother making their own _free_ manuals. I think this seriously comes into play when discussing Linux newbies and their need for coherent manuals. The biggest problem that I see is too many newbies not buying Linux. Why is this a problem, you might ask. Well, it turns out that because they didn't buy Linux, it didn't come with a paper manual. And everyone knows that a paper manual is so much more appealing when trying to find general answers. Digital manuals can be too in-depth or often overwhelm users by their searching capabilities that provide too many results. If more people would buy a bundled Linux distribution rather than downloading Linux for free - at least they couldn't say WFM! Does this really solve the problem though? Of course not, all the newbies aren't going to rush out and pick up a 50$ copy of Redhat 6 or Suse because they can't find out how to do X. Instead it seems that some alternative needs to be created. In my eyes, this alternative is before it's time. The world isn't really ready for digital books yet - sure, there are a few places stacking up for the new paradigm shift. I just read an article the other day in Infoworld that discussed traditional publishing houses like Houghton Mifflen, Bertelsmann, and Macmillan teaming up with technology partners such as Xerox, Hewlett-Packard, Reciprocal, and Fatbrain.com. However Infoworld agrees with me that "until portable technology had evolved to a point that's truly comparable to the print reading experience, certain types of information will remain in print for some time." In the same report Jack Staff - chief Internet economist at Zona Research - mentioned, "A book is as fine a PDA as you'll ever find. So as long as we still have paper, binding, and so on, there will be people that want to buy books.".

It seems like the technology for Neal Stephenson's "A Young Lady's Illustrated Primer" (Diamond Age [amazon.com]) does not exist yet.

What was that article about Paper Computers? Will that help?

Joseph Elwell.
• #### Online Linux help at Efnet #Linux (Score:2)

I would like to take this oppurtunity to invite Linux users of all skill levels, be they newbies or experienced users with a problem or willing to lend a hand to #Linux on Efnet.

We are a very high volume channel (over 10,100 users per day sometimes) dedicated to helping people with all matters Linux related.

Please check out our homepage http://www.linux-help.org [linux-help.org] for information about the channel and its rules.

You can also search through our bot "helper"'s extensive database using "helper ex keyword".

Hope to see you on IRC, Efnet #Linux's @Gnubie_

• #### Re:No Foolin... (Score:2)

Try searching on Usenet via any of its web-based gateways. Troll through your logs (/var/logs) to try and see what's going on when your connection drops.

Also, in keeping with your stated desire to have your linux box be a gateway and whatnot, try forgetting about X and Netscape for a while and just focus on dialup access, basic lan-networking, and ip masquerade or some such to share among several machines. Go to Goodwill and grab an old 486 for $20. When you can access your Linux box via telnet from your windows machine(s) (check www.download.com for some great free telnet clients for Windows), rip off the monitor and just use that sucker as a gateway and UNIX fiddling/programming machine. • #### Re:And guess what? (Score:2) It still does! ; ) • #### Try to see it from their perspective (Score:3) on Thursday December 30, 1999 @10:37AM (#1432476) Homepage "- Most newbies do not read documentation. If they do, they seem to only skim through it and choose not to "swallow" any of it." You are implicitly, even subconsciously, assuming that the newbie knows where to look and what to look for. If I don't know where to find the documentation, I certainly can't read it. Even if I know roughly where the documentation is, I may not know where within the documentation to go to, which means I'm going to skim through it until I find what seems appropriate--and if I'm a newbie who isn't too sure if I've found what I'm looking for, I may never find something that appears "appropriate," so I'll end up skimming through the whole thing. "- They are often rude. Most newbies who have access to my phone number seem to have a lack of respect for my own time. Believe it or not, people have accosted me verbally for choosing to no longer help them. I just hate when they get offended when you choose not to help!" If you give someone your phone number, you have implicitly given them permission to call you and ask of your time. If you don't want them to call during certain hours, say so. You may wish to give them an e-mail address rather than a phone number, since that way you can respond more or less at your leisure instead of being pressured immediately. (This assumes, of course, that they have an Internet connection in place, which may not be the case.) Bear in mind that if you tell someone to go away after you appear to have promised to offer some assistance, they may consider you to be rude, and respond rudely in kind. "- They ask far too general questions. "How do I get on the net with Linux?". Of course, if you decide to help with this question, they'll get irritated when you start getting into the details of how things work. You see, newbies want to gloss over everything without having at least some fundamental knowledge of how things work. There are currently other great (and not so great) operating systems for people who do not want to get into these issues." "How do I get on the net with Linux?" isn't horribly general, just goal-oriented. That's asking how to get from point A to point B. Newbies getting mad about you getting into details? If I ask you how to get from Picadilly Drugstore to Hal's Hardware, and you talk about how car engines work, you are 1) getting too detailed and 2) not answering my question. I obviously want a roadmap or directions. That's probably what you are inadvertently doing to the newbies who are asking you questions. The best way to handle it, IMHO, is to give them step-by-step directions, with occasional explanations of why each step works. Don't get too technical too early. What seems a mild current to you may be a riptide to them. The time for technical details is *after* they've got stuff working, and they are not in such a panic. The problem is that the things that are old hat and second nature to you now are likely to be utterly foreign concepts to newbies. It is all to easy to forget that, and I think that that is exactly what you have done. • #### GnubiBlues (Score:2) There is indeed a *lot* of information. The most valuable skills a Linux gnubi can have is the ability to frame usefull questions/queries and the ability to filter through large amount of info to find what they need *without* reading sequentially, line-by-line. For example, I want to connect to my isp via ppp. Fine. I need to know about networking, but I don't have the time or desire to learn it all. I need to be able to mine the mountain of 'Linux Networking' info to get what I need and go. This doesn't even touch upon the fact, tho', that I also need to get my modem configured and detected, which involves forays into kernels, modules, and all that those things entail. That's the toughest thing about Linux, the way one question inevitably branches into another, and another, and another. I think that's why a lot of folks lose patience. Most gnubis aren't accustomed to thinking and/or working this way, whereas most unix/linux devotees were drawn to Linux in the first place by virtue of these strengths, fueled by indefatigable curiosity... • #### Re:A guide to writing documentation for newbies (Score:2) 1. HOW-TOs need pictures. Or even a few proof readers. And people to consolidate them with all the others out there. I'm comfortable in UNIX, but I was setting up my first linux system recently, and I attempted to configure sendmail to work with PPP. What did I do first? Look for a HOW-TO on the web. I found at least 10 HOW-TOs for sendmail/ppp. None of them were even remotely the same. I picked the most readable, with the clearest steps and examples and plunged in. Worked great until I got to the part about rebuilding my sendmail configs.... all it said was "now rebuild the config file." The author apparently forgot that a newbie might not know that m4 is the appropriate tool to use. I guessed m4 based on the file extensions (and my UNIX background) but the m4 man page is awful, and it took some experimenting to figure out what to do. Granted, I won't forget that bit of knowledge for quite a while, but I can see where someone will less general UNIX experience would have given up and settled for never sending mail from linux. • #### Re:Concept Mappings (Score:2) Correction. Under Windows you have Windows until something goes wrong or you try and push the capabilities past what the interface designers intended. Then you realize that you have the worst command line of any modern PC OS, ridiculous strange behavior because of the DOS legacy (8.3 filenames anyone?) and in the case of Win9x, actual DOS still running underneath. You also have a poorly implemented registry system, with parts that are purposefully obfuscated to prevent users from mucking around and 0 gaurantee that the information in the registry has any correlation to the data on your hard drive. Case in point: Adding a new hard drive. I booted in linux and copied the complete contents of my old hard drive to my new hard drive. I booted off the new hard drive and everything worked fine. I then booted with BOTH hard drives plugged in. Quelle surprise, the drive letters where screwed up and all the software I had installed on my D drive was now actually installed on my E drive. The registry still believed they were on the D drive and therefore nothing worked. I've tried changing the drive letters, but strangely enough that option is greyed out. I got it working eventually, of course, since I am not afraid to muck with the registry. So, yes, /dev/hda1 is more confusing to someone who's been using DOS or Windows than C:, but it's all about a more solid foundation. Windows has a pretty paint job, but the foundation is made out of a bunch of toothpicks and glue. • #### Re:Better documentation, not necessarily more. (Score:2) You've made an excellent point. I could nitpick the title a little bit though. I think it IS more documentation that we need. As you've pointed out, most of the existing documentation is fairly unstructured (from a tutorial perspective at least.) It does not provide a tutor for the computer newbie. On the other hand, the documentation included with Linux gives you a better understanding of how your hardware/software works together than anything I've ever seen for the old mainstream OS's. We need new documentation that is less intimidating to new casual users and that can provide them with the illusion of understanding that they get from other operating systems. If the user at some point wants to delve deeper, all those howto's that we've grown to love still need to be available. For those of us that like to learn what's going on under the hood, well, we've already got it pretty damn good in my opinion. By the way, I'd like to offer some words of advice to anyone just starting with Linux. It's perfectly normal to feel intimidated. You may feel like there's no way you're going to learn everything. Fortunately, you don't have to learn everything to be more productive in Linux than you are in Windows. numb • #### Re:Newbies and documentation? Useless. (Score:2) The whole "I _LIKE_ being ignorant" mindset is increasingly popular with the advent of computers. Exactly. I don't think I could count the number of people I know who have gone out and bought a computer, brought it home, called me for help, and had actual PRIDE in their voice when telling me "I don't know a damn thing about these things." After trying to show them the basics, it always becomes apparent that not only do they lack computer knowledge, they actively resist acquiring any. In my mind, "I don't know" has always been one of the most embarrassing phrases I've ever had to speak. I can't count the number of times I've been up until dawn trying to find the answer to a question that had me stumped. How people can actually take pride in their own ignorance baffles me. Anyway, I'd have to say that there is already plenty of documentation out there. Sure, it may take a little searching to find it, and you may have to read more than a paragraph to find your answer, but the info is already out there for those who care to look. • #### Re:My Newbie HOWTO (Score:2) I must take issue with the "programmers don't write good documentation because they are too close to the code". Programmers write lousy documentation for two reasons: 1. They speak English as a second language (okay, this is more applicable perhaps to my current job) 2. They can't write period. Reason #1 is acceptable to me. I can't speak their language at all, so they're doing me a favor by speaking mine at all. Reason #2 is the overwhelming problem here. Too many people cannot write. Period. This extends far beyond coders; I recently reviewed an essay by an Art student which was almost unreadable, not for all the deconstructionist ArtSpeak, but simply for the poor grammar and spelling. Okay, now I sound like a bad actor doing a PSA, "stay in school! it's cool!" But hell, take some time when you choose to express yourself, being understood is important. As for the issue of being able to explain things in a sufficiently coherent manner for newbies: I would challenge you to always strive for this ability. You will find that it forces you to really make sure you understand the ins and outs of whatever technology you work with. I say this having taught things ranging from ethernet autosensing/negotiation to how to click and drag a file. When you break things down to where you're audience can understand them, you tend to learn a great deal yourself. • #### From a newbie to the Community (Score:2) The very first thing that should be available is a explanation of WHY Linux is good and better to use than other operating systems. Put a warm feeling in their belly about the challenge they are about to undertake. Second, explain exactly WHAT Linux will be able to do for them if they ride out the sometimes steep learning curve. Third--EXPLAIN that there may be some difficulties along the way---and that these are not reflective of a poorly designed OS, but rather ________________ (fill in your own answer). Then HOLD THEIR HAND. Acknowledge the fact that they come from a windows world and use pictures and illustrations that bring the concepts they already know from Windows over to Linux. Attempt to educate them on sym links, and file ownership before they ever see a command prompt. THEN lead them into using the OS. • #### Re:No one reads the fine manuals anymore... (Score:2) And you too, have an excellent point. An elementary school teacher once told me that she never taught knowlege to her students. Instead she taught them how to find knowlege. Needless to say, she was at the top of her profession. "Teacher, what happened to the dinosaurs?" "I don't know. Why don't you find out and let me know..." • #### Re:Tech Newbie (Score:2) Actually, I enjoy answering Linux questions! I reserve the 'Go read the documentation' attitude for people who should know. For example, take today. I was asked 'How do you change the mailserver address in Outlook', 'IS asked me to reboot the fileserver, but I don't want to, because I'm logged in, waiting for an AIM message', among others. These questions got the snotty response, because these people should know the answer from the mandatory training course, or because they have 'MCSE' in their title. On the other hand, I responded gleefully to the dozen emails and one phone call I got today about Linux problems. The documentation, as you have said, can be unclear and out-of-date. There was a reason I was being asked; the FM had been read, and yet something was lacking. Linux users have the bad habit of reading the manual, and I have never had a 'stupid' (see above) question from a user that has successfully made it past the installation process. You have my email, if you ever get stuck again, I will answer your questions as well. • #### Re:Man pages need *EXAMPLES* (Score:2) Practical example: the man page for ln says that the syntax is "ln (source) (destination)". Of course, the "source" is actually what the link is POINTING TO, and the "destination" is the name of the link. Most people (including me) thought that it was the other way around, and made a mistake the first few times around. If the man page had an example section that showed "Example: ln -s /usr/src/linux-2.2.0 linux creates a link called linux pointing at the directory /usr/src/linux-2.2.0", then most of us wouldn't have made a mistake the first time around. Ah, you mean like this [openbsd.org]: % man 1 ln ... EXAMPLES Create a symbolic link named /home/www and point it to /var/www: ln -s /var/www /home/www Hard link /usr/local/bin/fooprog to file /usr/local/bin/fooprog-1.0: ln /usr/local/bin/fooprog-1.0 /usr/local/bin/fooprog As an exercise, try the following commands:$ ls -i /bin/[ 11553 /bin/[
\$ ls -i /bin/test 11553 /bin/test
files have the same inode; that is, /bin/[ is essentially an alias for the test(1) [openbsd.org] command. This hard link exists so test(1) [openbsd.org] may be invoked from shell scripts, for example, using the if [ ] construct.
Yup, those are the OpenBSD manpages. No matter how you look at it, the BSD manpages are tremendously better than the Linux ones. There are 5x more of them, and those that are there cover 5x as much. For example, compare tty(4) [openbsd.org] with what you have on Linux. The Linux manpages are really an embarrassment. I've posted precise data on this before.
• #### Re:There's plenty of good resources out there. (Score:2)

Wow, between docs.sun.com and sunsolve.sun.com I can find just about anything I have ever wanted to
know about Sun hardware or software. In fact, most of the time, I find there is too much documentation and have to dig through to find the really important stuff.

Those sites are definately good, so is SolarisGuide.com [solarisguide.com], but there's not a million HOW-TOs like there are for Linux oriented installs.

AFAIK, Sun or HP doesn't provide Apache documentation, but look on Linux websites and you'll probably find 10 different guides to help new users get a Webserver going.

Same for Samba, same for a lot of software which "isn't Linux", but the Linux community provides HOW-TOs and tutorials for how to install on Linux, even though the software is well documented and runs on a variety of platforms.

I wasn't trying to make Sun or HP look undocumented, rather just trying to show that Linux has specific guides for setting up otherwise well documented software.
• #### Re:Newbies and documentation? Useless. (Score:2)

I agree - manuals have their priorities all out of order.

For example - look at the format of your average 'man' file. It starts by showing you the command along with every single option you could possibly type, then explains (in alphabetical order) what those options do. If you go farther down, it might tell you what the command does, and how to use it, if you're lucky. Take the 'tar' man file as an example.

This particular file also demonstrates another problem - manual writers think their program exists in a vacuum. I can't think of a time I've wanted to tar something without gzipping it as well, yet the option to gzip is only mentioned as part of the mess of options. It also talks about writing to tape being the main purpose of tar - now, anyone here who still uses tar to write to tape, raise your hand. Anyone? Anyone? Bueller?

It took me way too long to learn to use 'tar zxvf'. I would gunzip the file, then tar -x it with the file as standard input. I still don't know the best option group to create a .tar.gz archive. (tar zcvf would be logical, but gives the extremely obtuse error message 'Cowardly refusing to create an empty archive'.)

So it would be really nice if the 'tar' man page started, for example, by saying "To extract a .tar.gz file, type 'tar zxvf (file)'. To create a .tar.gz file..."
--
• #### The nature of Linux makes it hard. (Score:2)

Linux has several properties which make it difficult to write documentation:

1) Linux changes so quickly that documentation is quickly out of date after it is written.

2) There is so much choice in the Linux world that we have alot to write doumentation for.

For instance, I was leafing through my SuSE manual today. In the beginning they more or less have a section explaining this, and asks us to be patient. I began thinking about it as I read. They had many sections explaining how to do things at different levels (newbie -> advanced disk partitioning for instance). And they didn't even cover things like "how to use kde, or gnome", which is where most newbies will spend their time. Windows on the other hand can throw alot of money at "here is how to use the one and only version of our file manager".

The nature of Linux makes it hard! Maybe distributions can concentrate their documentation on how to use default installations, and leave the rest to us? I dunno. Difficult topic.
• #### Re:Documentation format (Score:2)

You take me for a newbie sir. I had this debate with RMS when he was first pushing texinfo as the GNU alternative to UNIX man. I told him that it was a mistake then for the same reasons. Basically:

• man -k does not find texinfo documents.
• Using texinfo docs from EMACS (or an EMACS like tool like info) is cool (do it all the time), but why could man pages not be browsed in the same way? I can think of some reasons, but they are all solved by some basic indexing techniques that were old tech in the seventies.
• Texinfo as a format is actually much better than roff. It is more readable, easier to learn and has a more regular syntax. However, it suffers exactly the same problems (e.g. being a general purpose markup language as opposed to a constrained UNIX documentation format) without the established conventions for accessing the documents on a UNIX (like) system.

Richard's response was to claim that roff was a useless format and its use would die out within the next five years. Well, it's been nearly ten since we had that talk, and I think it's time to admit that roff is here to stay. That's fine, plenty of things translate down to roff. The real question is this: how can we best pull all of the available Open Source software documentation together and make one coherent documentation system out of it. My recommendation hinges on using a format which is hostile to anything but the established UNIX standards for documentation reading while maintaining ease of use, low learning curve and maximum back-end file formats.

For an example of this format type "perldoc perlpod". If you have Perl installed, you will see the POD documentation for POD. You can almost certainly also type "man perlpod" and you can also go to the online HTML copy of perlpod [cpan.org]. All of these are generated by the tools that are part of the POD distribution which comes with Perl.

Someone suggested that these tools should be separated from be base Perl distribution. This would be a mistake, as they are all written in Perl, so you would always have to install both anyhow. And since most people install Perl these days, anyhow (even Solaris 8 from what I hear), POD is pretty ubiquitous in the first place.

In fact, I think (and boy, could I be way off base here) that POD is the only UNIX documentation format that has commercial support under Windows (given the ActivePerl distribution). Not that that matters much, but it's a datapoint.
• #### Re:loud and proud (Score:2)

Welcome to the cult of right-minded Linux users.
Down with the whining lamers!

:-P

• #### Re:The curse of being mainstream (Score:2)

Would it be too much to ask for you to stop bitching and start cranking out some of this easy-to-use code for "blind, deaf and possible [stet] emotionally disturbed farm animal"? Or are you too busy telling everyone how Linux should develop? I'm perfectly happy with Linux the way it is. Many other users are; many other developers are. What is it with this need people have to shoehorn Linux into one monolithic box? For the nth time: if there's money to be made providing an alternative to Windows, then some Linux distribution-maker will step in there; indeed, they already are: witness Caldera, for one. But don't expect miracles: Linux is Unix, and that isn't going to change. As an OS "anyone can use", it is not going to cut it.

#### Related LinksTop of the: day, week, month.

We can found no scientific discipline, nor a healthy profession on the technical mistakes of the Department of Defense and IBM. -- Edsger Dijkstra

Working...