Slashdot Mirror
The Linux Newbie Replies: WFM?
Thanks to Sensei^ for sending us a
link to a piece about dealing with new Linux users. Given the gigantic growth of Linux over the last year, this is an issue within the community: How do we deal with this influx of population? Everyone recognizes the need for more documentation, but what's the best way to do it? If you've got an opinion about the whole schmeal, click below and add to the conversation.
What the linux community needs is for a group of gurus to get together with one of those ever-popular journalism majors and create a light-weight web site (as in low color graphics) that provide examples of everything anyone would ever need to run linux. The site should start out with teaching the basics of the terminal, then go on to examples of X and the a few window managers, and continue with advanced terminal use. It shouldnt be more than 150 pages long or so, and it should also provide info on how to use man pages to gain even more info.
=======
There was never a genius without a tincture of madness.
It has been my experience that whenever I refer someone with questions to a manual, help file, man page, or HOWTO, they always come back with questions. I know it isn't a deficient manual, because usually the questions haven't changed.
I think our 'instant availability' society is the cause. They know I can give then a simplified, concise answer in seconds, while referring to the manual may cut into their coffee break and actually require them learning something! They may flip through the manual, perhaps looking at the index and actually finding that the manual has relevent information. But they never seem to read it.
Society sucks.
.sig: Now legally binding!
In working at an ISP here in Cleveland and having made many How-To web pages, I must say that pictures are very essential to documentation, and linux howto's do not have enough of them.
Although many of the text-based unix commands seem to have no need for pictures, even having them pictured would make things easier, so that a newbie would know where to type a command and when.
And then for the graphical interfaces that the newbie will want to see, there should be a LOT more pictures. Just seeing a page full of words is very discouraging, which is why I still hate man pages. I'd rather read 50 pages with pictures around all over the place than 10 pages of pure text. And many others agree. Pictures lighten up documentation.
- Mike Roberto
-- roberto@apk.net
--- AOL IM: MicroBerto
Berto
One thing that might be helpful is a sort of comparison between Win/Mac concepts and terminology to the Unix-style equivalents..
Et al, an explanation of the divisions between Kernel/Shell/X11/Window Manager/Desktop Environment and the Windows environment... Where to find how to change common system settings... What Linux/BSD is good at and what it is NOT good for.. [!]
The most killer thing for newbies seems to be understanding partitions, setting up X, setting up the mountpoints, 'startx', and understanding common commands like ls, rm, mv, cat, et al...
I dunno. All I do know is that a lot of computing enthusiasts hear all sorts of great things about Linux/BSD, hit a snag or ten, and dance right back into Windows, probably never to leave again. Perhaps a real-world document on how to get comfortable in a unix environment quickly would be helpful.
-troll taker
The most usefull tool to veteran UNIX users are probably the ever-present man pages. (Ok, so I once set up a system without them, but that is the exception not the rule) Man pages are complete, concise, and way to technical for most linux newbies to read. However if some brave soul would remake all the man pages to an extent that they would be understood by most newbies, and make a nice little index, I beleive that the newbies wanted to read the manuals themselfs could.
c . help BEFORE they attempt to read any documentation. The only thing that some people will accept is one-on-one walktrhoughs. Others will read documentatin, but only if it is physicaly printed on the pressed pulp of dead trees. These people should go out right now and buy a copy of LINUX FOR DUMMIES, or even better if somewhat redundant REDHAT LINUX FOR DUMMIES.
/. effect had already cripled the site to the point that it wouldn't load on my computer. So if I'm totaly off topic here, you have only yourselves to blame.
Nothing however will repress the newbies who try to get phone/IRC/YahooChat/email/personal/Psychiatric/et
On a side note, I did not read the article in question. The
Little Brother, watching the watchers
Two years later I delved into Linux and have been using it for a year and a half.
Although Linux has an extensive set of documentation and I wasn't a novice to Unix by then, I still found FreeBSD easier to learn even though I was virtually new to Unix.
I found that the documentation for FreeBSD was organised very much like a manual which was great to start with as I could work through it as I installed a system. The topics were also general such as 'disks', 'backups', 'serial communications' and it was easy to quickly find what you needed.
The Linux docs are organised by a specific 'need' and while it is great when you are after a solution to a specific problem, it is too unstructured for a newbie.
A newbie needs to be lead through the topics in a general fashion so that they can gain an overall picture - Linux docs don't really give a good overview.
It's 5am so I'm not very coherent at the moment - so i apologise if my opinion isn't very clear. I can't really give specifics (at least I can't think of specifics at the moment), but that is my general feeling about what makes Linux that little bit more difficult for newbies.
...if every Linux user dropped the attitude and helped the newbies instead of getting off on how superior they are because they know Linux.
Simply reading the manual/readme/whatever doesn't always work. If someone is used to OS xyz or 123 jumping to Linux takes a little help. I think that the Linux community doesn't want average Joe to use Linux because that would put average Joe on the same level.
"If you do not believe in the freedom of speach for those who you despise, you do not believe in it at all." -Noam Chomsky
I find it hard to hear such words springing forth from my own mouth, but the concept of a "solutions database" seems remarkably appropriate here.
Generally, I rail like nothing else against solutions databases, because my job is to enable people to solve complex problems in complex systems, and solutions databases tend to grossly oversimplify this task, which I find mildly insulting. also, we must consider the 90%/10% rule, whereby 90% of the calls/problem reports encompass 10% of the possible problem domain, but, conversely, the 10% of the calls which involve the other 90% of possible problems will also consume 90% of support staff's time.
However, we are talking about newbies here. And newbies happen to consitute 99% of the 90% easy calls. Thus a solutions database becomes a realistic and productive answer.
blah blah blah solutions database blah blah solutions database blah.... okay, WTF do I mean by solutions db?
think search engine, but with better semantics, and an astonishingly high signal to noise ratio. the actual database consists of answers -- and only answers, so we don't frustrate users by matching their query with an unanswered question -- which are concise, correct, specific, cross-referenced to more detailed information (THERE'S TFM). these answers will be submitted by whomever (one thing linux has is an amazing volunteer support base), but (here's the catch) must be filtered, combed, possibly edited, by a dedicated group of individuals.
What's the value add beyond the many linux-based search engines, specific help pages, newsgroups/email reflectors, etc? specificity and conciseness -- in short, a very good signal-to-noise ratio. the key is not treating this like a damn swiss army knife -- build one tool that serves one purpose well, rather than doing a shitsplatter job trying to cover everything with one tool.
if anyone is interested in hosting such a site, I'd be glad to help make such a thing a reality.
nathan
*urp!*
(Ok, so I lied about it being 10... :)
It's a small world and it smells funny; I'd buy another if it wasn't for the money; Take back what I paid (SoM)
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?
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 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 goes like this: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."
send all spam to theotherwhitemeat@ropine.com
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.
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."
send all spam to theotherwhitemeat@ropine.com
"- 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.