http://www.osnews.com/story/5180/Editorial_The_State_of_OSS_Documentation Exploring the Future of Computing en-us Copyright 2001-2012, David Adams adam+nospam@osnews.com Wed, 15 Feb 2012 11:16:23 GMT http://www.osnews.com/images/osnews.gif http://www.osnews.com http://www.osnews.com/thread? http://www.osnews.com/thread? I've got a suggestion Barry. STOP READING STUFF YOU DON'T CARE ABOUT Wed, 19 Nov 2003 21:18:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I will give you (finger in cheek) 1 million pounds for docs!.
Ok, sorry, your offers better than mine, I have nothing, nothing!

[/Pointlesspost] Wed, 19 Nov 2003 21:25:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Most users don't read documentation. If they can't understand how the software words within the first 5 minutes, they usually give up. I develop a intra-company CAD app, and our documentation is 'required reading' by engineers. Do they read it? No! Besides, most closed-source documention is not that good, anyway. A bit off topic, but, How many people can actually program their VCRs?

What OSS needs is to concentrate on intuitive user interfaces. No one sits down in front of Calculator and wonders, "Gee, I wonder how this thing works?" Wed, 19 Nov 2003 21:25:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I agree. An intuitive user interface is what the target needs to be. The users would then be guided by the program, and there would be little need for documentation. A great example of this tyupe of interface is: Evolution. Here is an email client that is powerful and easy and straight-forward to set up. Wed, 19 Nov 2003 21:33:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Windows doesn't have any better documenation. Heck, there is more documentation for Linux. I'd rather be stuck using Gentoo's magificant docs than the one paragraph help Wizard in Windows. Many, many distributions have great documenation. As I've said, I think Gentoo has better documentation than any operating system. I also think Debian has good documentation, as well as Slackware. I don't see what all the fuss is about. Wed, 19 Nov 2003 21:44:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Well, that "article" was more of a rant than anything else, but I agree with his sentiment. He is right on the nose, OSS doesn't have documentation and it needs it.

Oh, and the point about calculators, yeah if you go grab one of the $1.99 calculators, you don't need a manual, however try using something a bit more accurate for your analogy, like a high end programable scientific calculator. Most software has a much higher level of complexity than a calculator.

While intuitive UI's would be nice, the OSS community has also shown about the same level of interest in that as writing user documentation. So, until you mange to make your UI's so intuitive that we would never need any docs, write the documentation.

Oh, and using engineers for your example that people don't read documentation is ridiculous, because engineers are notoriously bad at reading any instruction manuals, worse than the general public.

Also, on the topic of programming VCRs, who cares? That isn't the core functionality, it's not why we buy a VCR. We buy them to watch tapes. If we dont' know how to cable it up to the TV & stereo, we read the manual on how to wire it, cause at least they provide one!

Also, regardless of how intuitive a UI is, there is always some feature or what not that you can't easily find so you go looking in the documentation for it.

- Kelson Wed, 19 Nov 2003 21:44:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? If you are such a good windows technical writer: please start to write for OSS

We can use it! Wed, 19 Nov 2003 21:44:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? This man has just spelled out the main reason I don't use OOS. Not consistant, no good docs or outdated docs. Yes it is free, but is it good. Overall I would have to say no, it isn't good. I would pay for good software and a good distribuion but it simply isn't out there. Wed, 19 Nov 2003 21:48:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? "Open Source documentation is terrible. There is no kinder way to put it"

Wow, what an overblown piece. Yes some documentation is bad, but most isn't nearly as bad as you make it out to be. Writing blanket statements like this does nobody any good and hardly represents ALL OpenSoftware. Many projects have excellant documentation but I guess fact doesn't garner page hits.

"Can you stop bickering among yourselves long enough to tell us how to run this stuff?"

Can you stop being such a judgemental a**?

Sorry you've had a problem with getting product X working. I suggest A) reading some on the excellant documentation that your distro puts out, for example the excellant docs that RedHat makes available B)Sticking to prepackged software made by your distro maker C) Sticking with software authors who specifically package their software for your distro. D) Taking advantage of any of the many forums dedicated to the particular pieces of software your using E) Use Google to research the particular problem your having F) Pay for a distro and use the support your entitled to G) Realize that many OSS projects are still mostly written BY and FOR technical people. H) Realize that if something is too hard, see the above tips.

Your basic issue seems to be that if your lost you find it hard to get on the right track. If you stick with what I recommend above chances are you'll get through it. Most of us do. If not then feel free to stick with what you know, ie Windows and its software. There can be a price to pay for using some Open Source Software. That price comes in to play if you don't stick to the rules I mentioned, and that price is your time. Many people don't want to have to invest time in learning how to do something. They want it to be as easy as the products they are currently familiar with.

If you don't see this as a fair trade for having access to Free software, then again stick with what you know. Then again feel free to write your own documention and then share it with the rest of us. That is what open source is all about after all.

Long op eds whining about how "geeks hate to write" without taking into account the fact that OSS authors ARE simply doing the best they can are going to fall on deaf ears. Like I said if you don't feel the software authors are doing a good enough job, feel free to do it yourself. Wed, 19 Nov 2003 21:48:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Perhaps it might be better to highlight some specific examples, and then remember that for every OSS application with some crappy feature, a corrolary exists within the proprietary world.

I have encountered bad docs for proprietary apps. I have encountered bad interfaces for proprietary apps. I have encountered bad support for proprietary apps. And I have encountered good stuff too.

Maybe enhancing this division between OSS and proprietary is just a false thing. Let's face it, there is good and bad for both.

Like I said, perhaps some useful examples of nonsemse documentation might do us ALL some good, regardless of the development method they choose.

Sorry if this seems like a troll, but I have had a gutsful of people slagging off OSS or proprietary software as if everything within them has got to be homogenous. Wed, 19 Nov 2003 21:49:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? On Windows, users just click Next buttons, that's it.

Only on OSS platforms, there is this need of RTFM, cuz it is by geeks and for geeks ... Wed, 19 Nov 2003 21:52:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? http://www.redhat.com/docs/manuals/linux/

Have you looked at some of these docs. They are pretty well written and go through setting up most normal user services.

What about a database man? One might say.

http://www.mysql.com/documentation/mysql/bychapter/index.html

I followed the instructions there and got mysql running in no time.

Suse has a huge and I mean SDB site with how to's about all kind of things. Just use the search.

http://sdb.suse.de/sdb/en/html/

This screams of a troll.

There are tons of documentation out there.

Could it get better? Yes.

I know the stats of comm software and docs. OSS stuff ain't that bad. Wed, 19 Nov 2003 21:53:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Can you stop bickering among yourselves long enough to tell us how to run this stuff? In terms we can understand? Please?

There is the problem. To be part of the solution, begin with "Can WE stop bickering among OURselves..."

Besides, if you look at the BSD documentation, you will see that much of it is great technical writing. I think you are painting with too broad of brush. Wed, 19 Nov 2003 21:56:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I think I barely saw very good documentation for my last 10 years of computer usage. There are too technical on many terms for computer illiterate and too short in content for technical oriented people.

Documentation for application are criticized for often not being helpful [I NEVER found any answer to my questions with Office help for example]. Documentation for developers are often too short on details or outdated. Both in the proprietary and open-source/free world. Open-source project for developers with lot of users have sometimes a good documentation for starting.

Today, the best help I get is in forums or mailing lists because this is direct user to user contact. It is quite common to meet someone that had solved the same problem as yours. But it works well only on good established products or projects.

my .02 Euros. Wed, 19 Nov 2003 22:02:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? "Gentoo's magificant docs"

I second that. Gentoo has very wonderful, verbose docs. While their install is more complicated than other distros, their docs cover each step in very good detail. Anything not in their docs has probably been discussed in the forums. Wed, 19 Nov 2003 22:06:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? It would be nice to have a standard documentation tool which could be used to reference every programs documentation, OR there should be something like a HIG for documentation. Wed, 19 Nov 2003 22:11:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I'd like to mention the info system, and man pages.
I know why there were originally two separate help systems, but why do we need two separate help systems?

I don't like being told in the man page that I should look at the info document. That's shoddy.
I'd like once place to look for help please, or at least one source which the documentation is generated from, so I can look at it using man, info, mozilla, whatever. Wed, 19 Nov 2003 22:13:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? FreeBSD has - EXCELLENT - documentation. And FreeBSD is OSS. Linux has terrible documentation, even though it's so popular, but Linux is not the only opensauce software. Wed, 19 Nov 2003 22:17:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? There are already hackneyed responses to the editorial: "My OS has good docs" "Nobody reads it" "You're an a**" to paraphrase a few.

Technical writing is a skill just like writing code. Unfortunately, most people don't have both skills. The responsibilty for good documentation begins with the code writer who should find a technical writer to collaborate with if necessary. The "community" can step in and help re-write existing, but inadequate or obsolete, documantation, but really, who knows the software better than the author? In my opinion, a good app without good documentation is only half complete.

PS. I do write documentation and have "contributed to the community" so go away and find another bon mot if you want to attack me personally. Wed, 19 Nov 2003 22:22:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Where is he supposed to begin?

Here in my town we're gonna have, this weekend, a GNU/Linux Festival, where there'll be lots of folks talking about Linux and Free Software; there'll be some courses; and an install fest. There'll be, also, (in the end of the festival) some kind of eletronic party with DJ and all that stuff.

Here in Brazil this kind of thing is getting very popular... in my opinion, this is the best way to introduce GNU/Linux to the common user.

Victor. Wed, 19 Nov 2003 22:23:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I agree, FreeBSD does have good documentation, but Linux does as well. Gentoo has anything you could you want for documentation. If not, there are plenty of resources on the web to find info on Linux. Wed, 19 Nov 2003 22:23:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? With OSS, user forums are great. The man pages are our friends. README files are there for a reason. However, the one word answer (for me personally) has been O'Reilly. Did I mention that I like books, like reading them, and really like my (small) collection? Wed, 19 Nov 2003 22:24:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Heard once in a land, far, far away: Read The Source, Luke! Wed, 19 Nov 2003 22:27:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? One of OSS's strengths is that a million people are developing a million different projects that, when joined together, because a Great System. But one of its weaknesses is that a million people are ... you get the idea.

Case in point: I wanted to install PHPGroupware. Coming from the Windows world, I am used to being able to insert a CD and have EVERYTHING I NEED installed and configured. When I am done, I have GROUPWARE. Ready to run. And should I have questions, mashing the "F1" key will bring up on-line help that's hyperlinked with an extensive index system.

Not so with Linux! First, I learned, I must install either MySQL or Postgresql. OK ... which should I choose? Solely because the (one) (1) (only) "How To" on installation used MySQL, that's what I chose.

So ... I had to hunt for documentation on how to make that work. I had to learn about creating a "PHPGroupware User ..." so first, I had to learn about users and groups!

Again: this isn't the problem. *nix is far more secure than Windows, and it's not going to be as easy to configure. I understand this. But could someone write a simple, step-by-step HOW TO that doesn't assume anything? That walks the poor n00b like yours truly through the process?

Once I finally get the SQL database and user/group stuff straightened out, I fully expect that I will finally be able to begin ironing out the kinks in PHPGroupware. I can hardly wait.

Like the author, I am also a solid Linux convert. Love KDE. Won't ever go back to Windows. But he's DEAD ON THE MONEY. I honestly believe that those who say that Windows is no better/easier have never tried it (or certainly haven't tried it lately). Anyone who says that setting up a software package under Windows is just as easy as under Linux should, IMNHO, be quietly led away.

And I've said this before here, so I'll say it again: people like me are perfectly willing to *PAY* for well-documented, well-designed free software packages, so the OSS community is even missing a chance to MAKE MONEY at this stuff, if they'll only pay attention. Wed, 19 Nov 2003 22:28:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Don't you see that you responded to someone's gripe about not having a single easy to use place to go for help with a snide response about how you were able to go to four different places to get help with four different topics? The point of the rant is that a newbie (well, a newbie who needs MySQL...) wouldn't know to go to each of those pages individually. Wed, 19 Nov 2003 22:37:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? @undeadpenguin: Gentoo has docs that cover everything? About the actual settings once you get PAST the install? It covers X in...about 5 lines. Oh yea, real in-depth documentation. Ok, so they do give you a link to documentation that is...outdated. And also at engineer level or higher. Granted, one should assume some level of sophistication with Gentoo but still.

The other does make valid points, in general OSS has terrible documentation. The Windows manuals are generally pretty good, or at least good enough to get the vast majority of users through whatever they need to do.

I know I'd love to see better docs from OSS people but most of what I need it on is not the install of the OS, or even the setup afterwards. I want it on individual programs. It seems like people don't realize that IF you make a program for the public domain and IF people are going to use it, you'd damn well better make docs for it! Putting in the help page "Documentation to come soon" after the product is released DOES NOT WORK. Wed, 19 Nov 2003 22:39:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Dude... what's up with you? Just:

apt-get install phpgroupware

Done. It's installed. Chill out. Got everything you need, configured and all. Don't even need a cd-player, just connect to the internet, and that's it. Ok? So, relax, it's easy, see?

Victor. Wed, 19 Nov 2003 22:40:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I believe this guys comments are right on the money. I recently switched to linux. As a small business owner, it was no easy task and still isn't today. Yes, there is some straight forward, good documentation available if you know where to look. But, you do have to know where to look. For me, I was willing to search around and find what was needed to get up and running. This takes a ton of time, which many of us do not have. But when setting up my father's new consulting business with WinXP, documentation was easy to find. When I say easy, I mean easy. Simply walk into any bookstore in your area and find all the info you need on Windows or any other Windows compatible application. Or go on any website selling books and you will find the same thing. Win OS and Win Application books are everywhere.

As a linux user who has switched from the Microsoft world, I can see why the average person is reluctant to even try a switch. There may be excellent documentation out there, but it is not easy to find. The linux world users need to see this as a problem. If it is stated as a problem somewhere, it is definitely something to look into instead of tearing the messenger apart. Yes, linux is an excellent OS. Yes, linux has the ability to challenge other OSs on an equal playing field. I truly believe this. But, linux needs to mature in the marketing and reality world. This means that linux is perceived as hard to use and geeky. If it is not then show the world that it is not. Make its use as technically easy as Microsoft and Apple. Until the bookstore is stocked with linux books in equal numbers as Microsoft and Apple, this excellent OS will lag behind. Wed, 19 Nov 2003 22:42:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Google it. Wed, 19 Nov 2003 22:49:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? From Post #7:

"...F) Pay for a distro and use the support your entitled to..."

Nice one. Wed, 19 Nov 2003 22:58:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? In Denmark you can check out: http://www.linuxbog.dk/
A number of fine books in various formats. And they get updateed regularly. Only in Danish, however. Wed, 19 Nov 2003 22:59:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? So, uhm, FreeBSD has good documentation, huh? So why not move some of that to into the linux space, as (surprise, surprise) 90% of it is actually applicable to it too!
In case noone noticed yet, most apps which run on FreeBSD actually run on linux too...or originated there, or whatever. They're not different, they're the same beasts. The fact they run under a different OS shouldn't, and doesn't matter from an end user point of view. So with the application software covered, what's really left is documentation on the OS itself. What, pray tell, would a non geek need documentation on the OS for? Most likely he or she will get the OS presented on a silver platter, preinstalled (either by an OEM, a system administrator or a good installer), and all the user needs to care about is how the applications work.

The problem with all these columns on what should be done to OSS software to make it success is that they're usually written by wannabe geeks, who forgot what it is to be a real end user. End users don't read documentation, don't care about OSS politics, really don't care what their OS is actually called either. All they do is repeat the tricks someone else showed them when they started using the system, and hang on to what they learned until someone shows them new tricks. No biggie.

My suggestion: Start thinking about what it will take to get linux on a corporate desktop from a system administrator's point of view. The end user couldn't care less. Wed, 19 Nov 2003 23:00:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? If think documentation is lacking for an open source project why don't you write it? Release the document under a compatible licence and stop whining. Wed, 19 Nov 2003 23:00:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I remember getting burnt to oblivion for suggesting good documentation in an article I submitted here some weeks ago. A lot of developers were offended. But the truth stings. Real programmers go to great lengths to document there project. Especially those who are well grounded in Mathematics where every step to a solution of a problem needs to be documented.

Personally, I judge open source projects based on the quality of documentation available for it. I shy away from projects that have little or no documentation. And I encourage others to do the same. But we need to define what a well documented project should look like. In my experience, a well documented project has the following;

a). A website that provides basic information about the project.

b). An on line installation manual

c). A getting started tutorial.

d). man pages bundled with the software

e). info pages bundled with the software

f). a help system containing a detailed step by step tutorial about the software.

g). a mailing list

h). a forum or an irc channel

i). a bugzilla system for users to browse for and report bugs.

Now, I know several open source projects that have all the above forms of documentation and a lot more. I'm yet to see a commercial software project that has all the above. It is right that most open source projects are poorly documented, but it is wrong to claim that their closed source counterpart are doing a better job.

The quality of documentation is really a controversial area. Not all open source projects can afford to higher a technical or document writer. Document writers volunteer to help a project if and when they are really passionate about it. Otherwise documentation is left to the author or developers of the project. Writing programs is by no means an easy task. Documenting it, is even tougher.
We can alleviate the problem by providing an easy avenue for anyone to help document projects. Many people want to help. But they don't know how to. Or they think it's extremely difficult and close to impossible except you have a PhD in Computer Science and web documentation. Again, large projects are tackling this problem.

We need to be cautious of what we demand from these heroes who do what they are doing for fun and are generous enough to share their work with the public. I see many individuals demanding too much and contributing nothing. These individuals aren't getting paid to document their projects for you. We can encourage them by helping or writing tools that make such tasks easier.

I see open source concentrating way too much on user experience and neglecting the comfort and experience of developers. I think that's silly. We need to focus on tools that make developing projects easier, more fun, more efficient and more productive. We need to break away from the pressures of satisfying the user and embrace the culture satisfying the developers. Wed, 19 Nov 2003 23:04:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I also get sick and tired on people boasting how good gentoo is, and how well it is documented....


News flash, people, end users do *not* need documentation on how to rebuild a system from scratch from (get this) another linux installation! Gentoo is good, but only if you have *a lot* of time on your hands, and are reasonably cluefull. By definition, end users are short on the first (It has to work *now*), and definately not the latter. If you want to wait for all your stuff to get compiled, go ahead, the real world will keep working along while you do so. Wed, 19 Nov 2003 23:06:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? The Mandrake 9.1 manuals are pretty good for a newbie, actually. Of course, for total newbies, there is always this:

http://www.amazon.com/exec/obidos/tg/detail/-/0764516604/qid=106928...

http://www.amazon.com/exec/obidos/tg/detail/-/0972679006/ref=pd_sim...

This is also an interesting site that can be found easily by typing "Linux newbies manual" in Google:

http://library.n0i.net/linux-unix/administration/nlm/ Wed, 19 Nov 2003 23:07:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Have you ever tried maintaining proper DocBook documentation against a fast-moving project? It's VERY difficult, and a damned sight more time-consuming than you'd think.

-Erwos Wed, 19 Nov 2003 23:08:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? @undeadpenguin: Gentoo has docs that cover everything? About the actual settings once you get PAST the install? It covers X in...about 5 lines. Oh yea, real in-depth documentation. Ok, so they do give you a link to documentation that is...outdated. And also at engineer level or higher. Granted, one should assume some level of sophistication with Gentoo but still.

http://www.gentoo.org/doc/en/index.xml

Gentoo is well documented. Go to bed now. Wed, 19 Nov 2003 23:10:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? As Hoyt said, it takes writing talent to create good documents. If you have the skill to take what information a software developer gives you and you can create a document that an average computer user can use, then may be you should be writing documentation.

The are tools out there that can help the authors. Even though it has a some what steep learning curve, DocBook is probably the best tool. A DocBook document can be converted to PDF, PS, HTML, and text. Man and Info pages are fine but having the capability to produce different file formats from one document is a better choice.

It is not easy writing good documentation. Some of the articles that have appeared on OSNews should be an example of how hard it is to write a good article. Wed, 19 Nov 2003 23:13:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? In the two and a half years since I've started using Linux I've found that using Google was actually oneof the best ways to learn about using Linux. It's no surprise that MS wants to buy that search engine in order to make searching for Linux material harder (compare searches on Linux in Google vs. MSN.com...) Wed, 19 Nov 2003 23:13:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? > An intuitive user interface is what the target needs to be.

The "audience" needs software that is stable and installable. Having to fix system variables and SO many other things just isn't practical when you wnat to get work done.

1- Polished software before developers start to work on the next gtk/Qt version.

2-And what OSS ralley needs is a general installer with a general directory layout ! (Distros like RdHAt and SuSE and many others will never contribute to this, for the pain of the users).

Documentation just reflects this state of things under Linux ( many times I read the documentation to found out that the commands and directories were changed in the next version I got). Wed, 19 Nov 2003 23:16:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? No that is not the point. Besides the MySQL link I was giving examples of docuementation by distro primarily.

If you use Redhat or Suse probably the two best supported versions of linux then you get docs and I list those for you. Many of the online docs for the distros actually lead you to the Linux documentation project.

Look at the Redhat docs in particular they give detailed setup instructions for basically all manners of user needs and services.

In addition, if I was setting up an oracle database I would look at the oracle manual. If I was setting up MySQL I would go to that site. Wed, 19 Nov 2003 23:21:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? http://www.tldp.org/ Wed, 19 Nov 2003 23:22:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I'm not a geek or a developper. I'm a user.

What i was looking for Linux is a try, just to avoid Microsoft Windows. Finally, i leaved Linux, because (actually) is an OS like "you are workink for the computer" (it needs a lot of configurations, technical knowledge) and i prefer "use the computer to work". Now i use a Mac. Don't misunderstood me, i agree with any person who likes Linux any other projects like this, simply is my preference.

But i agree with the article's writer: Linux is badly documented, for final users. If you are a geek, you will know its documentation the best. But, an user are looking, at least for a simple "Readme" file with installation instructions, or an User Manual (actually it seems the PDF manuals are the most used), or maybe an "First Run" screen. We (the users) don't know about rpm, dependencies, kernels, etc. We don't know how to install the last release of an Gnome (or KDE) app downloaded by a web (if we know where to download a file). Ok, we know this file is compressed, we uncompress it.. then? Some apps write in the README "Type ./configure | make | make install", but not all, and no one said we need to compile these sources (ohh ahhh they are "sources").

Linux may be hard for first users, but more hard if these things are undocumented. Ok, an intelligent person can write "linux" in their browser, but linux.com have a lot of info, not all for novice users.

I repeat, i agree if you like Linux as is. But, if you wish more Linux users, you need to write more user-oriented documentation, as Barry Smith said.

You imagine an app like Indesign without good documentation? In this case, how many of you learned to use it -and it's an easy app-? How many people will understand text blocks realtions, PDFx, trapping, etc.? Wed, 19 Nov 2003 23:32:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I can't believe some of the ignorance I see in the comments. People say "dude just apt-get " or just go here and do this. That is past the point... the point is that it's hard to get straight to the documentation you want to get to on Linux.

I have tried Red Hat, Mandrake,etc. and overall documentation is horrible. Sometimes it's not just a lack of documentation, but it's hard to find and get straight to. I've seen lots of KDE documentation, but even when I pretty much know exactly what I want to know about it's hard to find.

Although Windows doesn't have as great a documentation as i'd like it's infinitely easier to get to the documentaion I want to get to.

The point is how is your newbie Linux user supposed to find what they need ? Obviously Linux isn't as easy or intuitive as people say otherwise there wouldn't be as much need for documentation as people need. I don't know why some people out there can't admit it. I hate the OSS/Linux people who say Linux is perfect when it's far from it. NOTHING IS PERFECT. A good person knows everything has strengths and weaknesses and trys to work on the weaknesses so they aren't problems any more. I work on an end-user app and as good as I know my app is I know it has weaknesses and i'll admit it, something some Linux people won't do. I know all Linux users are like this but the few who are really get on my nerves sometimes.

Linux could use a help system like in Mac OS X and Windows where all help texts/help web pages can be viewed in a single application and can be easily accessed outside of using the app. For those of you who say "oh there is one and it's " end users don't know about it. You can have all the wonderfull apps you want, if people don't know about it then it doesn't mean crap to people. Wed, 19 Nov 2003 23:33:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I actually don't use Gentoo anymore, I switched to Arch (no downtimes for compiling). I actually didn't care all that much for the Gentoo distro in general, but I still stand by their documentation in saying it is the *best* of any distros I've ever seen. Wed, 19 Nov 2003 23:39:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? About the apt-get thing: i was just commenting that installing the software he wanted is very simple, and he was doing something overly complicated and unecessary.

What you say about Linux could be said about Windows too. Let me get my mom to use a Windows computer, and you would see if she finds it easy and understands everything.

To run an application, you should double-click the icon, but my mom doesn't know that. So you're saying there should be a doc saying "To run an application, you should double-click the icon", and you're also saying that my mom should read it?

The same thing with linux: to get some help, use man. The user doesn't know that? Well, my mom doesn't know how to run an application in Windows too.

Victor. Wed, 19 Nov 2003 23:45:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Well, to comment some more things...

All these comments about "there should be more docs to the newbie user" completely forget all the research that has been done about help in computer applications.

It is known that docs are bad for the common user. It's pretty simple: the user wants to be guided, not to get some docs to read and learn for himself.

Apple knows that. Take a look at this:
http://www.mactech.com/articles/develop/issue_18/006-021_Powers_fin...

From the article: "Help should be an interactive guide to accomplishing a task, not a static document."

Now, i find it an offense to say Windows has good docs or whatever. Windows sucks at it.

Apple has developed some stuff such as Coach Marks (read the link above), which are great. They really *guide* the user.

Users don't want help, they want guide.

Victor. Wed, 19 Nov 2003 23:51:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Yeah, like I always say, it's what you know. I think Linux is easier to learn than Windows, it's just that Windows is what most people are used to so switching to something else is hard for them. In my opinion, Windows is much more confusing than Linux. Why the heck would you have a 'Documents and Settings' "folder"?? /home makes more sense, as does /bin, /usr, /etc, /boot... I could go on. It's also easier to configure. I can change anything I want to on Linux. Not so with Windows. Wed, 19 Nov 2003 23:54:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Take a look at OpenBSD or FreeBSD. All the carefully prepared docs and man pages in the world. Buy a book or two w/ all of the money you're saving on Microsoft products and use those books to learn Open Source Operating Systems. Thu, 20 Nov 2003 00:00:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? No, I won't give it a rest, not even for a little while. I also won't read your article, because it began in such an insulting fashion. Had your introduction been posted to discussion here, I'd immediately have dismissed you as a troll. That doesn't bode well for an article the point of which (I'm guessing) is to influence the people you're insulting.

Thus I feel it is my responsibility to provide you with some documentation about rhetoric, in the form of a basic rule you may find useful in the future: when you're trying to influence an audience with your words, don't start by insulting them. I'd have thought something so simple would be a no-brainer, but apparently one needs to read the docs in order to figure it out. Thu, 20 Nov 2003 00:01:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Thank you sir. Your feedback is appreciated. It was not my intent to be confrontational, although I did expect negative reactions.

I did not intend to insult anyone. Provoke perhaps, but not insult. Thu, 20 Nov 2003 00:13:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Windows documentation:

Most people do not realize just how bad Windows documentation is because they do not use it. If you already know how to do everyday point-and-click stuff, you don't need to look at help files. Well, here is a quiz for you: in Windows XP, how do you reconnect to an SMB shared folder under a different set of credentials without rebooting? It's not documented anywhere... (answer: in the command prompt, "net use sharename delete" for each sharename that you have open under old credentials).

The help files that come with Windows cover only the problems that a person with 1 year of computer experience can solve themselves. Better information is out there, but you have to pay for it (books or premium support).

On the other hand, most major commercial software for Windows is quite well-documented.

----

Linux documentation:

Linux (basic OS functionality) documentation is excellent, but fragmented. It may be in man pages, info pages, the application's built-in help, random html files gzipped somewhere on your hard drive, a README that comes with the source, or on the package's homepage. Basically, the help is out there, but finding it can take time. Some distributions (Debian and Gentoo come to mind) maintain a good collection of documentation for common issues people encounter, which should be the first places to look.

As a matter of fact, to take care of newbies, the first time you boot Linux, a message box ought to pop up: "If you have questions, go to www.debian.org or www.gentoo.org".

Now, as for individual packages... Samba, CUPS, Perl, and Python come to mind as quite well-documented by any standard. There is enough to get a newbie started, and there is enough to solve most hard problems you encounter. Unfortunately, there are some poorly documented packages as well - *cough* Blender *cough*. For them, Google is your only solution.

----

Good documentation:

An obvious command (let's say "help" in a terminal, or an icon labeled "Help me!" on your desktop) that does fuzzy-logic pattern search through all man pages, info pages, random other documents on your hard drive, and a number of common websites. Common queries should pop up with a link to a newbie tutorial at the top. Basically, think of a Google for Linux docs. ( Implementation is left up to the reader Thu, 20 Nov 2003 00:20:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Correction: in "net use sharename /delete", there is a forward slash in front of "delete" (it didn't display for some reason). Thu, 20 Nov 2003 00:22:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I completely agree with you. 100%

I would like to say that I compare the documentation to the one of Solaris or Veritas VM. They are both excellent, and the point is, if you know what you are looking for, you will find it! And most of the time you'll find it even if you are not sure what you're looking for. Not so, with Linux.

Even if you use google as the only "entry point" to your documentation, if it's a Linux-related problem, you have to swim through a sea of irrelevant links, to find what you need. With Solaris or Veritas, you find it within the top 10 links.

But, want to see an easily navigable, searcheable document database? http://docs.sun.com/ Thu, 20 Nov 2003 00:32:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Agreed there is a lack of docs on some topics. But evidence TLDP and many FAQs and man pages out there. Perhaps many written for the geek rather than end user, but the docs are there. And solving Windows problems isn't exactly easy either sometimes. I also see a lot of misinformation in the windows community vs linux and bsd. How many hours are spent cleaning trojans and spyware as well.

Thanks to the docs, I've made it through net install of debian sparc, and configured lunar linux, crux, arch and many others. Installed ftp servers, sniffers, exploits, etc. Most of it through perseverance and often excellent albeit dated documentation.

One other point is that a typical install of say SuSE may involve thousands of programs. FreeBSD or Debian have almost 10,000 packages/ports which are only keystrokes away. This contrasts with windows, in which you don't have many of those packages in the default install. Thus it's of course harder to supply every answer to every question for each package.

For the moment, linux appeals to enthusiasts, servers, and 3rd world countries. That's fine with me. I don't see any reason at this point to try to compete with a $40 oem copy of xp that is pre-installed on a comp. Thu, 20 Nov 2003 00:38:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Why the heck would you have a 'Documents and Settings' "folder"?? /home makes more sense, as does /bin, /usr, /etc, /boot... I could go on.>

Documents --- ah, this would be where documents or documentation is stored, or perhaps the documents I (the user create).

Settings --- sounds like a place to go and change system wide settings.

bin --- Trash? A container for something? (The last place on earth I'd look to find a program. Which, in Windows and OSX live in logically named folders called "programs" and "applications" respectively. I guess the word "software" was far too sensable a choice -- *nix has a rep to maintain as the world's least intuitive OS, after all.)

usr --- user

etc --- anything else that doesn't fall into one of the above catagories. (A name about as descriptive as "stuff" or "morecrap".)

boot --- files related to booting up the computer.


---
In the flavor of *nix known as OSX, the files have logical names ... okay, "library" is a little vague, but "User" "Applications", "System" are self explanitory.

If only other *nixes would hop on board the clue train. Thu, 20 Nov 2003 00:40:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Noticing that you are monitoring this discussion, have you tried checking the docs out on OpenBSD like a few of us have recommended?
Of course, IMHO, the best way to test said docs is to install OpenBSD using *only* the docs. I did and I have a very secure, stable firewall that is patched and maintained using online docs and man pages. Setting up my OpenBSD box as a DHCP server took less than 3 minutes using the man page. Now that I know what I'm doing, it would take about the same amount of time using vi to setup the DHCP server as the amount of time it would take to setup my Linksys wireless AP as a DCHP server using the GUI.
You have to realize these people running the Open Source projects want above all for their stuff to work. They're unpaid so I would reckon their reward is seeing their stuff actually work, not writing docs that will change in 6 months.
You have two choices:
-Learn the software and help write docs
-Learn Thu, 20 Nov 2003 00:44:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Actually the best way to change the doc situation is write some. People think you have to code to contribute to a project but thats hardly the case. I wrote some docs for The Gimp and X Chat. Just ask a developer and see what we wants written. Thu, 20 Nov 2003 01:01:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? You make some some valid points. But it isn't OpenBSD that is making headlines now, it is Linux. I have said before (although not in this article) that I believe if someone downloads something for free they should take what they can get. However:

-Many commercial firms are trying to make a living selling this stuff. Not only do most of them not provide much documentation, the amount and quality appears to be getting worse. Mandrake used to include two bound manuals, now you get a pamphlet. Lindows, supposedly targeted to the newbie, includes a glossy 29 page brochure wiht a lot of illustrations and white space and pretty branding. Lycoris includes....basically what the community has written for them. Should the commercial firms not concern themselves with this?

-if it is free, then you take what you can get. But I have read many people bemoaning the fact that Linux is not catching on with the desktop as well as they want/expect. There are reasons for that, and it seems to me that one main reason is that Linux is intimidating if you don't already have the basics under your belt. It is HARD to teach yourself. I know, it took me almost three years to become comfortable with something as simple as downloading and installing source code, much less recompiling the kernel. There ARE standardized FAQs and How-Tos out there. But how is a new user supposed to find them?

I find it ironic that many free distros and applications provide better documentation (e.g. GIMP) thaN some of the commercially released software.

It doesn't matter how good it is. If the newbie can't figure out how to use it, what benefit does it provide? And not everyone has infinite resources in time and money to devote to learning an entirely new way of doing things. Thu, 20 Nov 2003 01:03:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? If you don't understand the instructions inside the package or some howto on the internet then you don't have the background knowledge to use the package, and if you finally use it it may harm you than do any good (eg. apache + security issues).

Read something, if you still don't understand then you need to read it again or search for deeper knowledge.

You can still try windows and windows apps and pray things go well. However if you need the job done and never care about setting things up again you N E E D to be aware of every aspect of the program installation procedure and parameters. What I've learned. What I already know now, won't need to read when things go wrong. Thu, 20 Nov 2003 01:09:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I really wish that some of the key man pages could be re-written. I greatly appreciate the work of those who have written the man pages we have, but some of them, particualarly those pertaining to the really powerful linux tools are so lacking, so obtuse, so syntactically inconsisent, obscure and befuddling that it defies imagination. I have come to the conclusion over time that there maybe a degree of deliberate obfuscation. Afterall if everyone could master the power tools of linux, sys admins would be easily replacable. Examples. BASH shell language, grep, awk, sed, regular expressions, extended regular expresssion. These tools are incredible. He who commands these tools rules linux absolutely. Believe me I have RTFM'S over and over and over again- more often than not they leave me more confused than I was at the beginning.

from the cp man page:
NAME
cp - copy files and directories

SYNOPSIS
cp [OPTION]... SOURCE DEST
cp [OPTION]... SOURCE... DIRECTORY
cp [OPTION]... --target-directory=DIRECTORY SOURCE...

DESCRIPTION
Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.

Mandatory arguments to long options are mandatory for short options
too.

-a, --archive
same as -dpR

--backup[=CONTROL]
make a backup of each existing destination file

-b like --backup but does not accept an argument

--copy-contents
copy contents of special files when recursive

-d same as --no-dereference --preserve=link

--no-dereference
never follow symbolic links

-f, --force
if an existing destination file cannot be opened, remove it and
try again

-i, --interactive
-H follow command-line symbolic links

-l, --link
link files instead of copying

-L, --dereference
always follow symbolic links

-p same as --preserve=mode,ownership,timestamps

--preserve[=ATTR_LIST]
preserve the specified attributes (default: mode,owner-
ship,timestamps), if possible additional attributes: links, all

--no-preserve=ATTR_LIST
don't preserve the specified attributes

--parents
append source path to DIRECTORY

-P same as `--no-dereference'

-R, -r, --recursive
copy directories recursively
prompt before overwrite


--remove-destination
remove each existing destination file before attempting to open
it (contrast with --force)

--reply={yes,no,query}
specify how to handle the prompt about an existing destination
file

--sparse=WHEN
control creation of sparse files

--strip-trailing-slashes remove any trailing slashes from each SOURCE
argument

-s, --symbolic-link
make symbolic links instead of copying

-S, --suffix=SUFFIX
override the usual backup suffix

--target-directory=DIRECTORY
move all SOURCE arguments into DIRECTORY


now please tell me since when cp "moves" files (ie.copy and erase). Explain to me how you remove a destination file prior to opening it ?. These tools are so powerful and yet their documentation is so limited. And try to find out stuff in the internet about grep/awk/sed etc. Given the power of these commands and how central they are to all things linux/UNIX you would think there would be lots of web pages documenting this stuff with lots of powerful examples. think again. Luckily I work with a guy who was born speaking regular expressions. I tell him what I need to do -he scripts it and I copy his syntax in an attempt to master it myself. I am making progress but `.god is it slown`



As a gentoo user I participate in the gentoo forums frequently(iwbcman). When I can help someone with a question they are asking I go out of my way to be as verbose as possible-slowly rethinking the steps involved and the myriad of possible paths that one may have already traversed. It is so easy to forget a step- particularly if you have done the same a hundred times(ie. becomes common sense) or if you haven't done it in a very long time(ie.forgotten). Some people have bitched at me for being too verbose, but most have really appreciated the time and effort I have put into helping people solve their problems. This issue becomes really pressing when it involves correctly configuring hardware-sometimes more that a dozen configuration files are involved- knowing which ones need to be modified in which way is so unbelievably complicated sometimes. Writing readable and understandable man pages is one thing- righting documentation that walks one through the myriad of configuration files(specific to each version of each distro), which is specific to each version of each software tool/driver/module is a task which by its very complexity, and the timeliness of information, is something that is at once nearly impossible and absolutely essential. Thu, 20 Nov 2003 01:14:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Sheesh, again one of the many ''it's not ready'' who talks for other people what they want or not want.

I'm wondering Barry Smith, where are your additions to the according to you very bad documentation? Or is this what you see as ''documentation''?

Granted, the GFDL is problematic. That's a problem.

OTOH, one who knows what Google or man means can find a lot of useful documentation. Easily. You have to know how to search, you have to read with a target instead of looking around like a dodo. The problem is rather the lazy, uninterested people who want to sit back and learn nada, niente, niks; exactly like you describe. Those who don't care what they run, how it works, not even a detail about it. Frankly, i don't even care if such people run . As long as their ignorance leaves me alone, i'm set. Go stick with a baby-OS, if that's what you prefer (and please patch your box since i'm tired of your spam. Luckily, regexp's in Apache make wonders).

Over and over again, there are these parasites in communities, not only in the computer world, who whine and contribute exactly this: .

This ain't good, that should be better, this sucks, that's bad. Then do something against it if you really don't like it. Like IPF vs. OpenBSD. People were discussing about IPF and it's license, massive threads about it, and in silence, Daniel Hartmeier wrote PF as a BSDL replacement. Thank you Daniel, you're one of those people who actually something.

It's like people who whine about politics, don't vote, and don't contribute in any way to make what they see as a problem any better. But oh, it's all sooo bad. Then when i ask ''what do you do about it'' the answer sounds silent. Do something! Thu, 20 Nov 2003 01:25:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Which explains how to change a video driver...

This is not a joke, I'm not trolling.

I do not know where to find a document explaining how to change a VGA driver. At least nothing up to date.

I have a machine which runs red hat 6.2, and I must confess I'm lost, I'm no Linux guy, but I'm not computer iliterate either.

I've been looking but I found nothing concrete. I've found info about the drivers being external or being compiled into the kernel. But nothing else.

I'm doing no bashing or trolling I just need some help. Thu, 20 Nov 2003 01:48:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? that many RedHat zealots will jump to your throat for running "such an outdated" distro of RedHat. Now I'll just lay back and watch the slaughter...

(I was once bombarded for asking a question related to RedHat 7.1 in a Linux newsgroup - this is going to be worse) Thu, 20 Nov 2003 01:53:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Judging by all the negative comments about this article gives everyone the general idea of how Linux people react when someone suggest that they make their OS friendly enough for the general public. At this rate/attitude linux will ---NEVER-- be ready for the desktop. Why dont they just port OSX to x86 so the rest of us can have a unix based choice without all this bull from the linux community. Thu, 20 Nov 2003 01:53:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Truly Good documentation is hard to find anywhere i consider truly good documentation to be documentation that caters for the newer users on face value but also contains any info a more technical minded user would require. And this is a truly rare thing.

Many Docs related linux related software (or stuff i have encountered) are extremely poor. I agree with the above post that there should be one souce of documentation preferably man.

A common document format between appliations would also be a nice to see.

However I do think this was a rant rather than an article. Windows help more often than not prooves to be utterly useless unless you know exactly what you want, how ever a similar format with similar functionality (index, contents, search etc) would be nice for OSS stuff.

I think a program that indexes all of /usr/doc and any other doc sources on the local system and then provides an easy to use interface similar to that of windows help (with search etc) would be a good step forward.

I prefer to use Linux on my desktop but imo its not ready for the unbathed masses mostly due to lack of support from hardware vendors in the creating of drivers.

I also think that better UI design is needed in some places. I would love to help plan or attempt to implement some of the things I mentioned if anyone is interested Thu, 20 Nov 2003 01:57:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? You obviously missed my point. Getting it installed isn't the issue. In Mandrake, it's included on the CDs, so I can say

urpmi mysql
urpmi phpgroupware

... and there you go. Installed. Ready to ... CONFIGURE.

Your failure to grasp this underscores the problem that people like me have.

Now: as for your comments on Windows' built-in Help, I want you to try this: go to a computer with XP and Office loaded. Create a spreadsheet. You will constantly be given suggestions -- even to the point that, when you're repeating the same action over and over again, the little help guy says, "you want to know an easier way? Try this."

Now say I'm having trouble with my networking. The message box that comes up to report this says, "do you want to run the network troubleshooter?" If I click, "yes," it takes me STEP BY STEP through what might be causing it.

Or, go into Windows help and search for help on "Modem." You'll get dozens of links, all crossreferenced, and all in a single place.

If you'll do this, you'll see why I said that I honestly believe that those OSS people who think that Linux help is just as good as Windows' can't possibly have tried the latter. There is no way any rational person could say that the help included with Linux, KDE or Gnome is as good. Period.

For the 1000th time: Remember, it's not just a matter of having some text. It's a matter of being able to find the precise info I want within a reasonable timeframe. Right now, with most Linux distros being composed of hundreds of scattered packages, each with its own maintainer, you get "refer to this How-To" or "check this website" FOR EACH LITTLE STEP in the process of making a system work.

EACH LITTLE STEP. Thu, 20 Nov 2003 02:03:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? With respect Paul, I think people are attempting to illustrate that truthfully, Linux documentation is on a par or better than OSX or XP. It is a fair point, to be honest, because you must bear in mind that XP and OSX only get better than "Click this... Does that fix it? If no, click something else.... Does that fix it? Then I don't know what to do." when you add their respective online documentation sites.

To be frank, Mandrake's documentation out of the box is better than that of XP or OSX.

Appreciably, Linux doesn't come with a tutorial telling you what every app on your system is, but then, neither does XP or OSX. You can install those and expect to be able to work right away, only to find that they don't come with a decent word processor, a very bitter pill to swallow, I assure you.

I utterly agree that we can do better when it comes to documentation and carefully teaching the user to use their system in an insightful way. That applies to Linux, OSX and indeed, XP. If documentation is such a critical failing, then none of them are 'ready for the desktop'.

Most people posting here are, unfortunately, somewhat wound up, because almost every week, someone posts an article here, stating why Linux isn't ready for the desktop. Every week, it is apparently something new, but coming from someone who has no intention of changing the situation (by coding or even merely suggesting improvements to a mailing list where people can make a difference) and no intention of ever considering Linux as their desktop OS anyway. Ultimately, it is a pointless, self-promoting exercise. Thu, 20 Nov 2003 02:04:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? The problem I've always had with documentation for any operating system is getting the answers I need. Like most people I don't read the documentation beforehand unless I haven't a clue where to even begin.

Where I fall down under M$ is that I'm reduced to hunting the forums anyways because the documentation doesn't answer my questions as a fairly competent system administrator.

Linux has HOWTOs, FreeBSD has the manual, at the end of the day, Google has a search engine.

Documentation by developers is often technical because the people who write it are technical and I find it more valuable that the dribble from M$ or Apple help which is apparently for monkeys.

I'd love a world where both documentation was available, but since I'm not a monkey I'll stick with technical documentation from developers who have a clue instead of psychologically profiled dribble from good documentation experts, that is aimed the marketing director who can barely turn his computer on.

Most of the problems listed here are related to software which is not trivial to install and hence requires documentation because its not a polished product. Thu, 20 Nov 2003 02:13:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? "......Most people posting here are, unfortunately, somewhat wound up, because almost every week, someone posts an article here, stating why Linux isn't ready for the desktop. Every week, it is apparently something new, but coming from someone who has no intention of changing the situation (by coding or even merely suggesting improvements to a mailing list where people can make a difference) and no intention of ever considering Linux as their desktop OS anyway. Ultimately, it is a pointless, self-promoting exercise."

Ok. I never said, nor did I imply, thatLinux was not ready for the desktop. I *stated* that before Linux will be more widely used, it will first need to become useable by the general population. I stated this as my opinion. If you have an opposing view, I am absolutely certain that OSNews would be delighted to post your article in rebuttal.

Regarding my contributions to the community, I have spent the last 3 years learning Linux on my own, since "RTFM you ignorant, worthless newb" was the standard response from most places I dared to ask a question.

I have contricubted a (for my limited budget) fairly substantial amount of money to six different commercial Linux companie, in addition to the Winex project and Codeweavers.

I have also contributed documentation to my local LUG, and I am currently attemptign to help, as much as time allows, in organizing and proofreading the data for a documentation project that was originated by the Lindows user community.

I have also, at my own expense, burned numerous copies of various Linuxdistros and distributed them free of charge to friends, family and neighbors. I have also provided whatever limited technical assistence was within my ability to various fellow users on forums and mailing lists. I have not received one thin dime of renumeration for any of this, nor did I expect any, nor do I ask for any.

But I do expect, and in fact I demand, the right to state my opinion as a contributing member of the Linux community. I may nto have contributed code, since I don't program. But I have put my money, my time and my effort, as well as what skills I DO possess into trying to build the community.

So I would deeply appreciate it if people woudl refrain from judging me until they find out who I really am.

Writing this article may indeed have been a pointless, self-promoting excercise. But I enjoyed it anyway.

Flame on. Thu, 20 Nov 2003 02:22:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? The documentation that comes with the distribution or OS itself isn't necessarily the issue. Yes, Mandrake does include better documentation for the initial installation (speaking from glad experience[g]). I would agree there.

So, I'm not talking about docs for "n00bs" in the sense of "never tried Linux before a'tall." I'm speaking of noobs in more advanced applications -- when you get past email, Web browsing, chat and writing letters.

Even with Mandrake, you're left hanging if you want to do much more than that. Just go look at their support forums sometime. "I set up a Samba server, but I still can't see my shares!"

Or, I myself answered a query from someone: "I installed Shorewall and it killed my (K)PPP connection." I knew from experience that Mandrake's default Shorewall installation doesn't know about PPP; you have to manually edit the "interfaces" file in /etc/shorewall. It took me a good bit of research to find that out, too. And when I whined about it, someone snidely pointed out that there's a comment to that effect in the "interfaces" file itself! But how was I supposed to know that??!?

Whimper. This isn't just a "noob" issue. I used that PHPGroupware example because it's a real-life thing that I'm dealing with right now. I'm not a noob at computing, I'm just a noob at Linux. Help, please?

I'm not afraid to read ... I just need to know where to look! Thu, 20 Nov 2003 02:23:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Get used to it.

I had an article posted here a few months back, and the first thing that became obvious was that those who were flaming me the most vehemently hadn't actually read what I'd written. At best, they had scanned through it.

You wrote a great article that was, as I said above, DEAD ON the money. Thu, 20 Nov 2003 02:27:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Open source solutions are no different from close source ones. There is a lot of bad and good documentation for both (usually a lot more bad.) Simple example, I would dare anyone to find better and as easily accessible/searchable documentation than what the Apache project provides. Thu, 20 Nov 2003 02:33:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I like linux because its easy for me to figure out but not for some dumbass looking for p0rn...
The internet was like this before it was useful, clean, & fast .
most of all it had people who knew how it worked & were there to share useful information & findings not the latest R&B hit on Kazaa...
Linux is kinda the same, most people who use it are curious & wanna know how their computer works & want TOTAL control..
But windows is for joe bob who never reads insturctions & never knew how to update their PC's.
No im not saying all windows users are like this but thats what windows is really (suppost to be) built for.

Linux isn't for Everyone but neither is Windows.... Thu, 20 Nov 2003 02:36:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Most of these comments are missing the point. End Users, the people that really count, mostly want to know how to accomplish tasks with applications.

They don't want to know how to install, troubleshoot, play around on the CLI, etc. They want to know things like how to work the spell checker and how do I attach a picture to my email?

For things like that, with some exceptions (OpenOffice & Mozilla, Evolution to some extent), Linux documentation sucks like you wouldn't believe.

Sit a newbie in front of Microsoft Word and ask them to do basic tasks and often they need to consult Help to do it. Microsoft *do* make usable, consistent, user-friendly UIs, but users *still* need the docs. In Linux, the UIs are often substandard - as has already been covered - and sometimes wildly inconsistent as well. And the key difference is that there are often no docs that cover simple, everyday end user tasks.

Take a look at the docs for KAddressBook, for example. The "Using" section hasn't even been written yet! Many other Linux applications are in a similar state. Thu, 20 Nov 2003 02:41:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I started Slackware 8 months ago. http://www.slackware.com/book/ got me through the basic install, then google & ldp 50-50 for the rest (with a couple of questions posted on my LUG's mailing list). It did take me a couple of months to get my parallel port CD writer working, but it took me 4 months to get it to work under Windows.

What I don't get, how is that "harder" than Windows??? Give a Windows CD to, say a Mac user and see if they can "just make it work now" (I don't suppose I could install & configure a Mac with AppleOS right from the get-go without doing a few lookups either). Sorry, but I'm getting bored with reading that "Linux is for geeks". Thu, 20 Nov 2003 02:41:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I forgot to add that end users often don't know where to look other than the manuals - if it's not in online help, it might as well not be there.

Perhaps there are a lot of resources already out there on the Internet (I suspect otherwise, but let's give those who says so the benefit of the doubt) - surely it wouldn't be too hard to incorporate these in the installed documentation? Thu, 20 Nov 2003 02:44:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? "
I do not know where to find a document explaining how to change a VGA driver. At least nothing up to date. "



Have you tried "xf86config" in the console or editing "/etc/X11/XF86Config"


What are your specs? Thu, 20 Nov 2003 02:57:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Programs changed alot so to me docs are useless and that goes for Windows, too. I started using Linux about a year and a half ago and the best place for me to get help is at http://www.justlinux.com Justlinux is a great site to get help, who needs docs. Thu, 20 Nov 2003 03:04:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? bin --- Trash? A container for something? (The last place on earth I'd look to find a program. Which, in Windows and OSX live in logically named folders called "programs" and "applications" respectively. I guess the word "software" was far too sensable a choice -- *nix has a rep to maintain as the world's least intuitive OS, after all.)

usr --- user

etc --- anything else that doesn't fall into one of the above catagories. (A name about as descriptive as "stuff" or "morecrap".)

bin = binary
usr = universal system resources
etc = configuration files
lib = libraries Thu, 20 Nov 2003 03:18:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I think the idea of Open Source is pretty good.
But we need more new ideas to improve the development. Thu, 20 Nov 2003 03:29:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? What is most important is to what degree software is useable without having to refer to a manual. With Linux and Windows both are fairly easy to use, using 'out of the box' features. It is when you need to install or customize software that Windows takes the lead. Most Windows users can install most software without refering to instructions, the same cannot be said for Linux. With drivers it is even worse. If Linux can get to the point where most user never even consider looking for instructions then it can be said that it has surpassed Windows. This does not mean dumb-down, it means making things to "Just Work". Thu, 20 Nov 2003 03:30:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? "Have you tried "xf86config" in the console or editing "/etc/X11/XF86Config"?"

To be fair, RedHat 6.2 would be running XF86 3.3.6 or so, which uses a different config style than 4.X.X, and you won't find much help for that anymore on the web. X -configure has only recently gotten to the point where it produces results that don't make you want to puke.

However: "man XF86Config" _should_ provide enough information for you to figure it out.

-Erwos Thu, 20 Nov 2003 03:36:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Dawnrider wrote:

Most people posting here are, unfortunately, somewhat wound up, because almost every week, someone posts an article here, stating why Linux isn't ready for the desktop. Every week, it is apparently something new, but coming from someone who has no intention of changing the situation (by coding or even merely suggesting improvements to a mailing list where people can make a difference) and no intention of ever considering Linux as their desktop OS anyway. Ultimately, it is a pointless, self-promoting exercise.


I 'am a person that would love to use linux as my desktop OS!!. I have been coming back to linux every year since 1999 hoping that all the crazyness would be resolved.

Here's what happened in my last attempt:

I saw a bunch of cool audio/video apps for linux that I wanted to try out. I was excited that maybe finally I could replace my Win2k box & my nearly dead amiga 1200. I got Red hat 9 and set my machine to dual boot Win2k/red hat 9.

first I downloaded Audacity.The rpm sent me into dependency hell. I downloaded every Lib they asked for and I still could never get it to run.

Then I tried Cinelera. It unpacked and ran right off the bat. Soon as I started loading video clips in/ or doinf anything in general, It would crash hard.

Keep in mind that I'm reading everything on the websites that tell me what I need.

Then I tried the new sneek peek at the new linux version mainactor studio. It would never make it past the splash screen before it crashed. (no docs at all).

once again I gave up on linux. Thu, 20 Nov 2003 03:38:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? That's true, and I agreee with you.

However, it's also a bit beside the point. Part of the basic for-free support model has always been "have you looked at this topic in the manual?" No matter how friendly the UI is, the documentation should always be there as a back-up.

Right now, a "read the manual" sort of reply doesn't get the user anywhere, because the manuals are in such a pitiful state. But, if you can say "look up the "How to do X" section in the manual, it's described there", and the instructions are easy to follow, we'll be 60% of the way there.

Redoing the UI isn't an excuse to avoid writing the manuals. Thu, 20 Nov 2003 03:41:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I'd be more than willing to do some technical documents. I need to expand my portfolio since I want to get a writing job (technical or non-technical).

Any projects people can suggest that I look into? The purpose of this thread, afterall, is not just to give opinions about existing documents but to have better written ones. Thu, 20 Nov 2003 03:58:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Try starting with the KDE docs http://docs.kde.org/

Many of those help files are either half-done or entirely useless. Thu, 20 Nov 2003 04:00:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? A. The three rules (the three "C's") of good docs: Make them complete, correct, and concise. The more complete, correct, and concise; the better.

B. If you want experts developing software for your favorite platform (not *Linux* experts, but the sort that write raytracers, simulators, and other rippin' cool software), the docs (see note "A" above) need to be written for *them*.

C. I fancy myself as one of those "experts" (see note "B" above), or at least an aspiring one, and I recently switched from GNU/Linux to OS X. There were just too many little things to keep track of with Linux (mounting/unmounting my thumbdrive just to backup my project, fooling around trying to get dual-monitors working (never got that one), fiddling with installing a kernel that would make the powerbook sleep/wake successfully). It's just exhausting filting through all that stuff just to get things working the way you want so you can get back to your *real* project.

D. The better-designed the system, the fewer docs req'd. {cough}BeOS{cough}. GNU/Linux/XFree/GNOME/KDE/... is thorny, and it's possible that there just isn't "good enough" docs for "experts" (see note "C" above) to stick with it. Perhaps this is where OpenBeOS will step in. Dunno.

E. Drag-n-drop software install: Welcome to flavor country.

Good night! Thu, 20 Nov 2003 04:22:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Ok, I used to work for a local ISP and I'll give you an example of what happens in the real world.

From my experience, people don't read what is on the screen, they ignore advice and they are tempted to screw with things they know nothing about. That is the reality.

Although I agree with the author about the sad state of documentation on the OSS world and the slow adoption of Linux, documentation isn't the be-all and end all.

The end user simply doesn't care and they're too lazy to do anything about it when they experience a problem. Every clueless user has atleast one friend who has atleast half a clue about using a computer. Which is easier, ringing up their friend with a dumb question or taking the effort to look at the problem in the documentation to solve the problem?

Now, if the authors main audiance they want to win over to Linux is the technically literate audiance who is willing to do the hard slogg and read the fabulously friendly manual when in doubt.

The fact remains that unless the user is forced to use Linux at work and forced to learn how to use it, Linux will never get into the home environment. The IBM-Compatible PC won over the home market not because it was superior but because it was used at work. People accepted the status quo even though there were superior alternatives out there; Amiga, Atari and Apple. Thu, 20 Nov 2003 04:22:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? usr = universal system resources
I thought USR was Unix System Resources. Hmm...I guess my bad.

etc = configuration files
I never liked that name. Why not call it what it is? Why not call it "config." Granted, it is really a minor point, but it would be more intuitive. Thu, 20 Nov 2003 05:05:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? What is most important is to what degree software is useable without having to refer to a manual. With Linux and Windows both are fairly easy to use, using 'out of the box' features. It is when you need to install or customize software that Windows takes the lead. Most Windows users can install most software without refering to instructions, the same cannot be said for Linux. With drivers it is even worse. If Linux can get to the point where most user never even consider looking for instructions then it can be said that it has surpassed Windows. This does not mean dumb-down, it means making things to "Just Work".

I couldn't agree more.

Intuitive != weak Thu, 20 Nov 2003 05:07:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I can't disagree with ChocolateCheeseCake ... nice 'nick btw.

Academic papers are quite similar - they stay within a closed circle, are read by few but are very detailed. Same thing with computer documentation: its detailed, few read it, even fewer appreciate it and everyone tries to figure it out on thier own.

I've found the best documentation to date for me has been man pages, the Linx Howto (particularly Kirsch) and FreeBSD hand book. GNOME and KDE are really intuitive as it is. I wonder how much documentation it "really" needs. Besides, at some point average users won't need to poke into kernels and command prompts. People complain that MS documentation is choppy and its only on-line "you don't get a book anymore".

There's a culture in society that teaches people to only read the manual when there's a problem. Usually reading the manual first saves more time. Either we -somehow- unravel this culture or .. not to sound too elietist.. I'd prefer not writing documentation for noobs. I'd seriously like to tackle something more technical (looks really good in a portfolio ). Thu, 20 Nov 2003 05:09:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Nope, Unix System Resources Thu, 20 Nov 2003 05:30:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I've just spent a week writing a new manual/systems manual for a new application. It is a shrinkwrapped product, however the documentation was abysmal.

Of the documentation that does exist, it is either outdated, inaccurate or completely lacking in detail.

And then there is the third-party-created reporting tool that was built-in for reports. After staring at it for a while, I contacted the supplier of the software, who forwarded me their supplier's "manual." (A Windows Help file).

This manual was easily the worst manual I have ever read in my life, yet it is for a popular(?!) QuickReports reporting library.


OSS is the only source of poor documentation? Only if you want to start a flame war, or if your head is burried in the sand.

Please, no more rash generalisations. That's sensationalist reporting - which is invariably BS. (This rash generalisation included free of charge!) Thu, 20 Nov 2003 05:44:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? ALL the moreso because I myself have attempted to have changes *added* to existing manpages by filing RFE's against the product in question, only to be told that said company would neither implement the requested change nor would they pass it upstream so the products maintainers could do so. I would have to track them down myself, manage to contact them, explain my situation, and pray that whoever it was wasn't having a bad hair day. And then wait.

For changes that were _simple_ and _made sense_ and _made better documentation_.

Better yet, If I could have somewhere found the proper documentation for how to WRITE a manpage properly, and how to properly ENCODE IT, AS a manpage, (in terms that I as a new user to such things could easily grasp, such as the wonderful 'start here' irc-style tutorial on www.vi-improved.com), I could have actually submitted a proper *patch* for the docs that would have stood a better chance of being included as an update to the manpage... but even the guy responding to my RFE said that he didn't grok manpages well enough to implement the change himself!

I agree! HELP! Thu, 20 Nov 2003 05:52:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? The problem isn't that there are no docs or the docs are too bad.
The problem is how the information is supplied.
Using OSS means browsing lots of web-pages/forums, while the "normal" user expects to have a hardcopy and mainly he isn't as skilled in getting information/docs from the net as maybe a developer. getting the requested infos quickly needs kind of practise.. and time, and who's got time today? Thu, 20 Nov 2003 09:10:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I use Gentoo and, whenever documentation isn't enough, the Gentoo Forums provide all the help I need. Today documentation isn't so important because one can instantly contact other users online and get help straightaway. Why bother writing an entire manual which few will read when you can just wait for a person to pop up on the web forums, IRC channel, or mailing list? Thu, 20 Nov 2003 09:30:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? This is the same problem as many large companies face today: there is a lot of knowledge in the brains of advanced users and developers which is never committed to paper (or any othre form of documentation). In my experience there is better documentation in code comments than in most user manuals.

Companies try and solve this by creating "knowledge databases" which are make-works and never do half of what was promised, but the internet makes it possible for forums, channels and lists to create a 24h free help system which (generally) works .

Maybe there is a commercial opportunity for a company to sell documentation to other projects' OSS. It doesnt violate the GPL and I'm sure many people would buy them.

In response to the article, if I may make a similie: you want to drive a car without having lessons? Linux and associated software require you to _learn_ about them and youre obviously going to get nowhere until you do. Millions of others have successfully learned 'Linux', so it can't be so hard. Thu, 20 Nov 2003 10:12:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? "How many people can actually program their VCRs? "

I can I usually forget the exact way to do damn Sony and their stupid you have to turn the VCR off to set the programed record!

I also enjoy reading Manuals for a new VCR it allows me to find out about the nifty features Thu, 20 Nov 2003 11:09:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I've seen quite a few comments on here (and similar discussions) along the lines of 'we might not be very good at this thing but neither are Microsoft'.
That's a fair point when responding to the FUD but we need to give people reasons to move from their MS software. That means being better where the users can see it's better.
I do agree there isn't enough focus on documentation for propriatory OR OSS software but at least WE can do something about it. ;-) Thu, 20 Nov 2003 11:57:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? After a couple of years living with dual-boot, I decided to kiss Windows goodbye a couple of months ago, and I don't regret it. Actually I convinced my girlfriend to swith too and now she's a happy Mandrake user.

But one thing is right, Linux can be still quite frustrating. There's apt-get, red-carpet and synaptic all right, but still it's not as easy as the "setup.exe -> next -> next -> finish" solution from Microsoft. And while this is not adressed somehow, Linux will still be a niche/corporate product. I know it's not an easy task, there are so many distros etc, but hey, we managed to put a man on the moon using 64K computers, so we should be able to solve that too.

In a way it's nice to see how much people love Linux and get angry with any criticism, but by the other hand this love can be a bit blinding. Linux documentation still sucks. I spent 2 long, frustrating hours yesterday trying to make an FTP admin tool work, and it's still not working because at the end I discovered I would have to recompile proftpd with an optional module. Sigh.

If your only answer is "Microsoft documentation also sucks", well, so that's a good chance to be _better_ than Microsoft. Thu, 20 Nov 2003 13:30:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? he must be kidding............ he said that just as if anybody could understand c/c++/perl/whatever code and even if everyone could ? how many programmers are able to understand someone's else code ?????
In fact, this the real fact : linux is for geek, oss is for geek just because we can't require anything from someone who is doing this for free. You like it ? fine. You can use it ? fine ? you can't figure out how it works ? I don't care.
and don't tell me this is not the case, just look at the doc provided with, say, lopster..... gaim, xmms..... in the gaim's doc for exemple, in the versio 0.60 I used to use, there's not even a line telling where the file is stored when someone send you a file via msn protocol.

the mplayer's doc is awfull, in the lates release when you type mplayer -dvd 1 (as it used to work), there's a error message telling that the use of -dvd is deprecated, one has to use dvd:// and it stops. Why, why ? if the program is able to make a link between -dvd 1 and dvd://1, why didn't it make the translation by itself and launch the dvd.....
I love this program but when my girlfriend wants to watch a dvd with mplayer, I had to tell her that if she wants it on the tv she has to write -vo dxr3 and -fs -vo xv on the screen, of course she forgot (and she's right) so I made 2 alias one called tv and one called screen.........
Pfffffffff, after almost 7 years of linux stuff, I'm fed up with the help button telling nothing, the obscfucated command line and the fact I have to pray when I buy a new device,I pray hard just to not have to update my only one years old kernel nor I don't want to recompile. I can do it eyes closed but it's just boring me.

the next machine I bought would be a mac os X one, and why not a win2K one, I sometimes use one in my office and with cygwin, it's pretty usable.


that's it, when someone asks to read the source just to learn how to use a program, I would like to die. Because this guy is living into this own sphere of pure geekyness and it's sad.


Djamé Thu, 20 Nov 2003 13:45:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? For a desktop user Linux still has a lot of rough edges.... That is where linux is at.... for those new users that are having difficulty patience... Its coming it might take a couple of years to be where you want it though....

I am a long time linux user - (6 years 1 1/2 years as my main operating system). The problems with the help system on linux as I see it...

Man and info systems are nice but don't take advantage of features available in a gui environment.... Having two systems is a bit of a pain....

It would be nice to be able to search all help from the one location...

Howto style help needs to integrated into each application perhaps with an explaination on forums and other help resources that a person can access online...

My practical advice for those trying to handle linux right here right now.... Practice your search engine skills... This is the best way to get up to date info on your system. Find a few good forums... I use www.pclinuxonline.com and www.mandrakeuser.org Thu, 20 Nov 2003 14:09:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? 1.
> When normal people buy a software package with which they
> are not familiar, the first thing they do is look inside the
> package for instructions.

Do you mean that you first bought a Linux distro and _then_
decided to get an idea what's it all about?

2. At the LDP, there are some _very_ good guides for noobies.
Take a look, e.g., at the guide by Machtelt Garrels. It's
much better than any commercial book on Linux I have ever
read or seen. Thu, 20 Nov 2003 14:14:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I had a similar experience to the parallel port CDRW mentioned above. I have a USB 2.0 cdrw that most linux distros configure properly. Sometimes it needs the append trick in lilo, in Arch, I had to do a bit more. But it always worked.

For Windows, I went to the manufacturer's site. Tried all the drivers and none would work in Win 98 or Server 2003. It would work in XP or using Roxio, but never the way I wanted. Thu, 20 Nov 2003 14:30:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Mr Smith has hit the nail right on the head.

There is a sickening, misguided pride in making things difficult to understand, and if you don't get the gist of it, you are a moron. This, from people who think Bananistan is a country in the Caucasus.

RTFM is obsolete, because TFM is unintellible, their object of the game is to give half-answers so when asked again, they can spout their elitist mantra.

A computer is a tool to achieve a task, the simpler the better, it is NOT a way to show off your pseudo-IQ.

Kudos to the author. Thu, 20 Nov 2003 15:21:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? So, about 50 posts ago, mtdman posted a bit of a manual.

NAME
cp - copy files and directories

SYNOPSIS
cp [OPTION]... SOURCE DEST
cp [OPTION]... SOURCE... DIRECTORY
cp [OPTION]... --target-directory=DIRECTORY SOURCE...

DESCRIPTION
Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.

Mandatory arguments to long options are mandatory for short options
too.

-a, --archive
same as -dpR

---

I do technical writing as part of my job.

Can somebody please explain to me what the hell that gobbly gook meant?

In the mean time, I've just mailed that off to the guy I took my 700 level tech writing course from as yet another example of real life bad technical writing. Thu, 20 Nov 2003 15:37:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? This is just a thought, so no shouting please...

A great many OSS apps do have bad documentation as in none, overly technical, badly written or out of date.

Some commercial software also has bad documentation as in overly technical or badly written.

When it comes to OSS I'm prepared to be more forgiving as I'm usuall gald to get an app for free (or even at all). Writing is a skill as the autor of the article pointed out, however many tech doc autors DO NOT possess that skill so stating that coders often can't write good docs is a moot point.

Leaving paid writers out of the equation for a moment, is it possible that OSS documentation suffers due to the decentralised nature of development?

Centralised (usually, but not exclusively commercial) developers have an inate advantage when it comes to doc writing. Analogy time : (I know that I'm going to get flamed by the Ayn Rand wannabes, but please read the whole paragraph following) Planned political economies show similar advanteges. Market economies have different advantages. Perhaps mixed economies are the most generally advantageous to the citizenry.

Can this model apply to software development? Possibly. The LDP is a good example. Maybe some of us should get on with the job of writing alternative docs based on the developers docs and re-submitting them back for possible inclusion as beginners' guides?

???

Jason... Thu, 20 Nov 2003 15:46:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? ..and I come to this conclusion because I see most other OSS projects to be well documented. Expecially, as I said, FreeBSD, but there are others as well.

Linux, for all it's popularity and hype, has the worst man pages and the most uninformative info pages I have seen. Not to mention that forcing the user to use info instead of the ubiquitous man, is just plain fucking mean. Thu, 20 Nov 2003 15:58:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I agree with the author. OSS typically has poor documentation, and this poor documentation prevents non-technical users from using OSS effectively.

I'm an open source programmer and I'm guilty of not writing documentation too. My reason for not writing documentation is that open source programming is what I do in my free time, and writing documentation is the least fun and least satisfying part of software development, so I don't do it. (But I will make efforts to change that.)

If open source projects are to successfully replaced their closed source counterparts, they do need good documentation. They need more than that though. OSS projects typically lack consistent user interfaces, which also makes things difficult for non-technical users.

What I would like to see is an open source operating system, with open source applications, that all have a consistent, well designed user interfaces. Of course, a good, consistent help system would be needed to. This way, a non-technical person would be able to adjust to an open source environment more easily, and may even find it favorable to Windows or Mac OS.

Though, to make this idea happen, the open source development needs to be structured like a software company. There need to be people who's job it is to enforce software consistency and quality. Otherwise, each individual programmer would just do whatever they wanted to fit their needs, and not the needs of non-technical users.

This is part of the reason why I am involved with the OpenBeOS project. I believe it is structured so that problems typical of open source software are less likely to occur.

I understand the needs of non-technical users. At my last job, I worked with them and wrote software for them daily. I want to apply what I've learned and do open source software the way it should be done. I don't really like Windows, I don't like Apple or Mac OS and I don't like Linux because of the problems I've mentioned.

This leaves me with little choice but to create open source software how I think it needs to be done. I want to excel where other open source projects are lacking. I will do my best to address the complaints of the author and make better open source software. Thu, 20 Nov 2003 16:02:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? This is the kind of thing that makes OSS work. I have seen several posts that move beyond flaming me or agreeing with me. Even now, there are people out there thinking about *how*to*fix*this*.

That is why OSS has come as far as it has as fast as it has.

BTW, I agree completely. If the Linux community ventered on the LDP and got some tech-savvy (hint, hint) members to incorporate all the existing documentation into a single integrated database, then stuck a user friendly GUI on the front of it, life would be a lot easier for us non-programmers.

B.S. Thu, 20 Nov 2003 16:06:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I want to apply what I've learned and do open source software the way it should be done. I don't really like Windows, I don't like Apple or Mac OS and I don't like Linux because of the problems I've mentioned.... This is part of the reason why I am involved with the OpenBeOS project

Not liking Apple is one thing, and maybe I'm biased as I like Apple as much as it's possible for someone of my particular political persuasion to link any private enterprise. However....

I'm not sure why a BeOS use should dislike Apple. The BeOS user experience was very similar to the old Mac OS (and I'm not talking about mulit-threading or app launch times etc, just the look and feel). Gassé and a whole hose of Be developers came from Apple after all.

As for Mac OS X, what's not to like about it other than that some people would prefer that it was (a.) Free and (b.) somewhat less processor intensive?

My only criticisms of OS X are that I'm aware of the Finder, whereas in the old Mac OS I was just digging around on the HD; and the System folder is a bit mre impenetrable than in System 6/7 or OS 8/9. Thu, 20 Nov 2003 16:23:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Before I delve into the article itself, I have a general question for the community at large:

Does the Linux community want to see wider adoption of the Linux platform?

If the answer to that question is yes, then wider adoption means end-users would be using this software; in turn it means that these end-users will start using the software on home PC's. (M$'s success was made by business users bringing the software home, and using it at home)

If end-users are going to be using the software, then there are responsibilities and expectations they have as to how an OS should run.

1) Turn it on, and it comes on- End-Users shouldn't have to go crawling around XF86Config files to make standard functions like their desktop come up. A default installation(notice I said default, not customized) of Linux should come up the first time, every time. This is the bar that was set by Microsoft; in order for Linux to compete in the same arena, it must be able to do these minimum functions, otherwise an end-user will simply go back to using Windows.

2) Software should be easy to install-Remember, end-users came from a Microsoft culture in which wizards, setup files and AutoRun is used predominantly. Asking an end-user to chase down dependencies, or to use the CLI to install with apt-get, urpmi, or yum is an unrealistic expectation.

Mandrake has made a good interface with it's package manager; Redhat's and SuSe's isn't bad either, but it's not yet to the point where a user can stick a CD in, have the CD autorun, and either call on these managers to install and hide from the end-user (notice I said end-user, not enthusiast)all of the dependency tracking or to do a direct install of the software, without CLI messages.
(Sorry to the enthusiasts; Microsoft works based on GUI interfaces, and to compete, Linux has to do so too.)

3) Documentation(What the core of the article was about)-
The man and info pages are good sources of information. No one disputes that there isn't documentation out there to help new users (when I first started out, it's what taught me), but here's the thing:

a) I know how to use Google and Yahoo
b) I know how to use forums and newsgroups
c) I know what an FAQ, HOWTO and mailing list archives are.
d) I know what a man page or and info page is.

I'm in the industry. I'm paid to know.

End-Users don't. If Linux is to be more widely adopted, then one of the bullets the community has to bite is the acceptance of users who need a start point for information.

I agree with much of the article. I think he was trying to show how much frustration end-users go through to install Linux and utilize Linux on their systems. On some points, I'm not sure he may have put them as tactfully, or elequently as he could have, but the essential point came off.

The general opinions I've seen so far have included:

*if it's free, then it's their own problem.
*RTFM and leave me alone
*How can you say the documentation is poor? There are these tools to do this with?
*Create your own

1) If the goal is wider acceptance, then answers like if it's free, then it's their own problem is irresponsible. It's not helpful; it actually hinders people from using it.

2)When I first started using Linux about 6 years ago, I ran into this type of thinking quite a bit when looking for answers to questions. Once again, not helpful and irresponsible.

3)Linux enthusiasts are coming from a point where they know where these resources are. Forums, FAQ's, man pages...that's all assumed knowledge. Many of you on the forum are linked with the IT profession, or actually work in the industry, based on what I've seen from user responses.

End-Users don't have that knowledge; unless they are pointed out to the end-user, either by a GUI based help system, or by printed documentation that highlights or incudes FAQ's, links to helpful New User sites, or HOWTO's written for end-users (not like some of the howto's I've read, written by the developer, for the development crowd), they aren't going to know where to go.

And the response of "If they don't know, then they shouldn't be using it" reinforces the wrong idea; that only enthusiasts and developers should use Linux. Is that what enthusiasts really want? I would think the goal is to be a dominant force in both business systems and home systems. To do that, thinking like this and comments like this need to be left behind.

M$ doesn't have better documentation; in fact some of it is insanely worse that I've ever seen for Linux. It's that for end-users, certain basic issues and problems have been simplified such that it really is a "Point and Click" solution for things like installing programs, drivers, and peripherals.

4) I think creating your own is a good idea, as long as you have experience with the product. To take it one step further, a new user manual with default or basic instructions, tips and FAQ's on doing consistent functions in Linux should be included with the software, by the manufacturer (online, or in print). (Each distro is different, but all of them have a certain amount of functions that are universal)
Then if the community wants to contribute to a distribution centric type of documentation to include with the download, I don't see why Mandrake, or Fedora or Debian would have an issue with it.

Essentially it comes down to "Do you want this to be used by end-users?"

Brian Cross
Systems Administrator
Southwest Microwave Thu, 20 Nov 2003 16:33:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? As for Mac OS X, what's not to like about it

Well, let's start with its GUI "drawers". Thu, 20 Nov 2003 17:23:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread?
So, about 50 posts ago, mtdman posted a bit of a manual.

NAME
cp - copy files and directories

SYNOPSIS
cp [OPTION]... SOURCE DEST
cp [OPTION]... SOURCE... DIRECTORY
cp [OPTION]... --target-directory=DIRECTORY SOURCE...

DESCRIPTION
Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.

Mandatory arguments to long options are mandatory for short options
too.

-a, --archive
same as -dpR

---

I do technical writing as part of my job.

Can somebody please explain to me what the hell that gobbly gook meant?


Okay, grab an english dictionary, and follow along.
The "SYNOPSIS" part explains the syntax you can use for this command. SOURCE is pretty self explanatory, DEST or DIRECTORY are the destination file or directory you want to copy SOURCE as/to. So that basically covers the firt two SYNOPSes. For the third you actually have to do some understanding reading and logic thinking...what is says "multiple sources", it isn't kidding. Try to deduce what "cp foo bar baz" does. Does it copy foo and bar to baz? And is baz a file or directory? So, the third syntax comes in handy, cp --target-directory=baz foo bar, which copies both foo and bar to destination directory baz. Where's the hard part? Oh, maybe it's in "Mandatory arguments to long options are mandatory for short options too.".
Guess what, all it means is that cp takes long and short syntax for options, and that mandatory arguments are, well, mandatory for both syntaxes. Wow, really, amazingly technical english. And you write technical documentation for a living?


In the mean time, I've just mailed that off to the guy I took my 700 level tech writing course from as yet another example of real life bad technical writing.

I hope he makes you fail the course on hindsight. Stick to what you know, typing out what someone else already wrote. You obviously lack the base knowledge and logical deduction skills required to write technical documentation based on something slightly more complicated than a comic book. If that seems harsh, it is. Go away, we don't want you. Thu, 20 Nov 2003 17:30:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? and it's because of people like you that Linux community has such a bad name. But, congratulations on poo-pooing someone who is training to be a professional technical writer, and could have contributed to Linux in this very lacking field. What is the likelyhood he'll help, now? Thu, 20 Nov 2003 17:34:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? "On Windows, users just click Next buttons, that's it. "

Windows users also all have weatherbug, gator, savenow, bonzibuddy etc. installed

Maybe required technical knowledge is a good thing? if it's easy to do the right thing...it's easy to do the wrong thing...

that's it...we should start requiring liscenses to use computers... Thu, 20 Nov 2003 17:51:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Barry hit the nail on the head!!! I've been learning how to use Linux in various flavors, over the past 5 years and one of the stumbling blocks is how the information is presented to a person needing to perform a task. The information assumes prior usage and knowledge in Linux/(maybe UNIX?) Yes, DOS/Windows/OS/2's documentation is better illustrated from the manuals from Microsoft/IBM, but, like Linux you are almost always force to pay $ for books written by someone else who was paid to take the time to write the information in a "layman's" language. But, for a person interest in a Linux distro other than RedHat, SUSE, Mandrake, will have a hard time finding a book at their local bookstore that will help them on their journey of learning Linux(Ok, if a person is lucky, they'll find a book on older versions of Mandrake, Slackware,etc.) Sure, Amazon, or Borders, or B&N have books on other distro, but Lindows 4.0, Knoppix 3.x, Lycoris, Xandros? Good Luck searching! Maybe the Linux Documentation project should find volunteers who can write the documentation in the "layman's' language and have it as part of their site. Remember, Linux has already won over a lot of technically proficent users, If Linux supporters want to battle MS in the desktop arena, and win 30 to 55% of the desktop market, having the documentation in a easy to understand format, with excellant examples, will go a loooong way in gaining new converts from Windows!!! Thu, 20 Nov 2003 18:04:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I agree with him. Think of it this way - he is one of our end users giving us feedback. If you talk like this to all your end users, you will never get them to use the product.

The average user doesn't sit in front of a computer and think like a geek and you have to document from the perspective.

What makes Linux great is Freedom of Choice, but that can also hinder in certain aspects - documentation is one. But myself, I like that. It plays more towards my hacker tendencies. Thu, 20 Nov 2003 18:19:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I work for a medium-sized ISP here in Brazil and we have a web hosting offering which is pretty much automated. Automated in a sense that the customer fills a form in our homepage and the system create an account for him, someone here register his domain and at the end the system sends an e-mail with everything that he needs to know about his account.

This e-mail includes not only his login and password but also unvaluable information on how to deal with FrontPage, some FTP clients, the usual e-mail clients, some other things about our offerings and all the proper URLs for additional info at our homepage. It is a little bit too verbose for my taste but it surely is nice written and doesn´t expect at all a tech-savvy user to understand how to publish his/her pages.

Even so, our callcenter receives in a daily basis at least a dozen or more calls from customers which didn´t even bothered to read the damn e-mail to know his login information. Most don´t read much more than that... All they want to know is their login and password.

Almost everybody that calls our callcenter can not setup an e-mail account in Outlook or Outlook Express, which are, by most "standards", intuitive applications. These people can´t learn how to use a FTP client, no matter how good our documentation or the program´s documentation are.

The bottom line is that the end-user simply don´t want to read a manual even if he have to. Maybe some of the "I´m not a tech head" who showed up here so far read it once in a while but I can tell you: the REAL Average Joe don´t.

I´ll tell you again: THEY DON´T READ MANUALS. Period.

Also, some others people here have said that closed source apps provide much better documentation, that can hold the user´s hand at every step. Sorry, that´s not true either. Put someone who never used CorelDraw or [insert your favorite drawing program here], ask him to draw a logo with curves, bevels and what not and points him to the Help system to see if he can do it.

He won´t do it. No matter how intelligent or unintelligent this person is, he/she won´t acomplish it. He needs to LEARN the application before. If he really wants it, he will do it it either by taking classes or buying books.

If one wants to use Linux, he can buy a retail box from one vendor which likely will include a nice printed manual. I don´t know about the others, but I heard that SuSE offers two heavy printed manuals which are really good. One also could buy a book about Linux in any bookshop. Even here in Brazil, we can find it everywhere.

That being said, I´d like to point out that I also think that documentation in Linux needs some help. Not for me, because I think it is fine right now. But some people, like my wife, can´t understand most of it.

KDE and GNOME embedded help system often covers issues regarding KDE or GNOME respectively. Maybe the Linux vendors could make a more complete help system and put in there instead of the original ones. Maybe not, because it could hurts their book/manual sales. I don´t know.

DeadFish Man Thu, 20 Nov 2003 18:40:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Granted, I think that some of the arguements are a bit weak, but he brings up some very good points.

I'll give you an example... I started dinkin' around w/Linux way back in the Redhat 5 days of yore. At that time the documentation situation was much worse than the questionable state that it's in today!

When I first started investigating Linux it was largely due to me being bored with the MS offerings at the time. I'd started with old Atari 8 bit computers in my youth (ah... Miner 2049er), bought my first computer while I was stilll living at home (a sharp new Amiga 500, with all the trimmings!), and had eventually wound up in x86 land, largely because I couldn't then, and still can't justify the cost of moving to Macintosh Land.

But Windows at the time sucked (Yeah, yeah... Some would say it still does), and in my forays into the unknown, I'd came across references to X-Windows, which eventually led me to the land of Linux, small though it was at the time.

But the situation then is very similar to today in that someone coming over from Windows, though they may be aware of Linux, or some other Unix offshoot, has no clear source to get up-to-speed as far as what Linux can offer them, and what others are offering for Linux.

I remember spending hours just tracing down words and verbiage that did't make any sense to my non-Unix mentality. With MS, you had at the time Dos and Windows. Never mind that Windows was a GUI that allowed easier interaction with it's DOS backend. It was very black and white to the user: Dos and Windows.

But when you got into Linux, you had the command line, X-Windows (Xfree), Window managers, libraries up the ying-yang, tons of obscure terms and tounge-in-cheek naming conventions, and there was no one source to learn about all this.

Much less was there one source to retrieve this type of information from.

While today we do have several notable resources for the newbie (and I myself still refer to linuxquestions.org more than I like to admit), it's still a huge learning curve just to get up to speed on Linux and what it offers to the person considering checking it out.

You have Linux itself, which to the untrained is comperable to Dos (ie, they're both CLI), but to the Windows-based people, Dos is old-school and buggy. They don't get what a powerful, robust CLI brings to the table, and there's no really good source to explain this concept to them.

Then they of course have their choice of UI's. Gnome and KDE are the top two (Go KDE!!), but as soon as you realize that, you have to begin understanding the strengths and minuses of each, in addition to how they will or won't impact what you can easily run under each.. Whoops! You chose a Gnome install and are trying to run KDE or some other QT-based app under it without any of the supporting files or libraries! Of course that's not what the user sees... They see something along the lines of "missing library dadada...".

You need really simple, easy-to-understand documentation to teach these types of concepts to people, if in fact we want to continue down this "Lots of choice makes Linux better" road.

Now, once you understand the basics of Gnome and KDE (and I won't even touch on any of the other UI's out there... Some are cool (XFCE), but all present yet another learning expedition for some poor soul who just wanted to see what was out there beyond Windows), you now have to grapple with XFree, and how that impacts your GUI, and perhaps more importantly, how it is impacted by your choice of video card.

You have to remember... Windows may or may not suck, but it comes with drivers for a ton of hardware and video cards. The user doesn't have to know or care about drivers, or how the backend of the OS works... They just have to wait for Windows to see the video card and it'll be automatically setup for them most cases.

Then once you have the basics down, and are able to actually boot into a Windowed environment, you have to deal with all the crap involved with getting your particular hardware up and running.

As an example, Suse 9 is the ONLY Linux distro I've ran that's automatically detected my scanner correctly and configured it for use. The ONLY ONE out of probably 20 distro's I've booted at one time or another. that's saying something considering that Windows can be up and running with it in no time!

How about tweaking your environment once it's running? Let's say I want better mouse response, hopefully comperable to Windows smoothness.

Well it can be done, but typically you must edit your XFree86Config file. This is something the casual user just does not want to do, and arguably shouldn't have to.

I could go on... Different distro's all arrange their file structure slightly differently... Startup runtimes differ from vendor to vendor. And while more vendors are finally dumbing down the basics of Unix so that the average user can configure their system easily, there's still huge inconsistencies between distributions.

Similarly, library and supporting file conflicts are still a potentially big problem, no matter how nice of a package manager you're using (apt-get rocks, but 's nowhere near as intuitive as a Windows install!).

And while you can argue all you want about how the vendors should play nicer and all conform to some basic standards, there's no universal authority or source for learning about all of this. Thu, 20 Nov 2003 18:41:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? The Linux documentation site's great, but as the author points out, how many newbies are aware of it.

I'll go a step further: Of all the newbies that are aware of it, how many will likely understand all of the new terms and verbiage they're likely to encounter as they search for answers to their problems?

The aforementioned Linuxquestions.org site is amazing, and one of the first consistently great sites for asking and learning about Linux. However even there you'll run across a lot of questions that are just left unanswered, or are unanswerable because the person asking the questions doesn't understand Linux well enough to word their questions in an answerable manner!

I personally think the problem isn't only documentation, but is also a lack of vision on the parts of the developer community and the vendors who are pushing Linux. Instead of dealing with the basic issues of usability and comprehension, they're too focused on making Linux better with their own little tweaks.

There's simply too much personalization of Linux at the Vendor level. While organizations have been formed to try and resolve some of this (ala UnitedLinux), most of their efforts have been thwarted by infighting and an inability to concede points to one another. Look at United Linux... If you ignore the hypocrisy of Sco for a minute, can you jump from Suse to Mandrake to Redhat and have the same RPM's work equally well on each? No.

Can you presume that because you've figured out the basics of Redhat 9 w/Gnome that you can now understand Gentoo? No.

Howe about this: I can jump from Windows 95 to 98 to 2000 to XP, and potentially to NT and have the same executable work most of the time (Yes... Something specific for XP will not run on 98, and something specific for Win95 might not work under NT, but in theory, most software runs under most Windows.

Whereas if I have downloaded a lot of software for Redhat 9 (any vendor really, but I'll pick on Redhat), and now am checking out say Mandrake, then my RPM's likely will not install without errors.

And to get back to the point of this article... There's no source to really tell me why this is.

Yes, the experts would say "Well you're talking two different versions of Linux", but to the unwashed heathens coming over from Windows Land, they know that their Win95 software worked when they upgraded to Win98. And they know that WinXP also runs their worn out copy of Office 97, so it's hard for them to understand how one could be talking about two different distributions of Linux, and still not be talking about the same thing ("Windows is Windows; Why isn't Linux Linux?")

It gets deeper too... Once you've figured out the basics, now you have to deal with kernel recompilations and upgrades (All right... You don't have too, but while chasing down facts and documentation, you're bound to come across references to such things).

How about why this program will compile with this version of gcc, but this one will not. And just what he hell is gcc anyway?

Blah blah blah....

Long story short (Too late!), Linux needs to either work towards some standards now, or face the fact that if Linux is going to succeed, that only one or two large companies are going to be succesfuly with it. As a new user, I would be much more inclined to go with a name brand that's recognizable, and (hopefully) one who can guarantee that they'll dumb everything down for me, and make sure that my software doesn't break as I upgrade little bits of it here or there.

The documentation is important too though! The above "only one or two companies are going to win" speel assumes that those companies can dumb both the interface, and all of the complex little bits that make up a Linux system down to the level that Joe Blow can understand, and it assumes that this company will dumb the "How To's" that litter the Linux landscape down to just a few click-and-learn types of help sessions (again... Like Windows has with its help system).

You might not like either Apple or Microsoft, but you should be able to see the powers that having one vision and one company in control brings to the table.

I'm not saying it's a better system than Linux, but one vision and controller (company or person) can provide a much more cohesive base of software for the user. Look at Apples OSX. In theory, anyone could build a GUI that looks and/or performs on par with OSX, over a Linux backend.

Why has no one done this yet? Because there's no one company pushing this. I love KDE, but I'll be the first to say that it's power bring with it a fairly steep learning curve if you want to truly exploit it to it's fullest potential.

OSX is as easy to use as it is because you had one company/person defining how it was going to function. MS has handled Windows in a similar manner in that you generally know what you're getting into with any Windows app. Common shortcuts, look and feel, etc.

As soon as all the OSS developers can put aside their differences, and agree that losing some independance and control to some common standards (both with documentation as well as software behavior), Linux will truly become a contender.

Until then, I feel it's best an OS for either the "Power User", and/or those who like to tinker.

If we're looking at newbies in particular, who only want a good Windows alternative (in other words, they want a new tool to do their computing with, but they don't want to become a Linux convert), then it's a good OS only for those newbies who have a technician who's both patient and knowledgable handy. Anything less just isn't good enough to win over the casual users of either Windows or OSX, because as soon as they run into a problem that's not resolveable with a few mouseclicks, they'll be thinking "I could have done this with Windows myself! And I don't know anything about computers!". Thu, 20 Nov 2003 18:43:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread?
and it's because of people like you that Linux community has such a bad name. But, congratulations on poo-pooing someone who is training to be a professional technical writer, and could have contributed to Linux in this very lacking field. What is the likelyhood he'll help, now?

Yeah, truth hurts, doesn't it? The likelyhood of him helping is about slim to none if grasping a manual page is already too hard. I mean, this guy is supposed to be a technical writer. One of the requirements for that job is to translate more or less complicated snippets of developer documentation into end user documentation. And `man cp` already *is* end user documentation, go figure. Personally, I know my way around all kinds of documentation, code comments included. Google, mailinglist posts, newsgroups, FAQs, HOWTOs, README's..I've seen it all, and there hasn't been much occasions on which I had to give up on a problem. It's all out there. But hey, I'm a professional. I get paid to be able to solve the kind of problems you don't find the answers for in a 'linux for dummies' book. Fast forward to the end user. Who in heck so you think I solve these problems *for*? Exactly...the end users. Manuals? They don't want manuals, they want someone to show them the trick once or twice, and then they happily repeat that.

The key to get Linux on desktops is to supply it preinstalled on the hardware people buy, at no additional cost. It is time some government looks into the OEM contracts Microsoft has forced on their slaves^W^Whardware vendors. Thu, 20 Nov 2003 18:44:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I mean, this guy is supposed to be a technical writer. One of the requirements for that job is to translate more or less complicated snippets of developer documentation into end user documentation. And `man cp` already *is* end user documentation, go figure.

I believe that was the point. 'man cp' or just about any man page looks more like the documentation I, as a developer, would write for my personal reference, or maybe something I'd put in my code comments before I write the code to parse the command line arguments. I've seen a lot of bagging on Windows' and other closed source programs' help docs, but the reality is that in order for OSS to supplant closed source on desktops the docs have to be better, and man pages are no easier to read than the crap that spews out when you type 'help command' in the command prompt in Windows. There's a reason why the help in Windows has such a bad reputation, and that reason is because it's useless. Because people are used to docs being useless, they don't read them. If the first time someone accessed the documentation or help for a program (or operating system) they found it useful, they might actually use it more often.

Personally, I know my way around all kinds of documentation, code comments included. Google, mailinglist posts, newsgroups, FAQs, HOWTOs, README's..I've seen it all, and there hasn't been much occasions on which I had to give up on a problem. It's all out there. But hey, I'm a professional. I get paid to be able to solve the kind of problems you don't find the answers for in a 'linux for dummies' book. Fast forward to the end user. Who in heck so you think I solve these problems *for*? Exactly...the end users. Manuals? They don't want manuals, they want someone to show them the trick once or twice, and then they happily repeat that.

Exactly, so why doesn't the documentation start with the tricks, and then go into detail for those users that want the details? Why doesn't 'man cp' start with
cp "source file" "destination file"

instead of
cp SOURCE DEST

and furthermore, why is destination shortened to DEST?

Note: I'm not saying Windows is any better, as here's the similar example from that side:
help copy
Copies one or more files to another location.

COPY [/V] [/N] [/Y | /-Y] [/Z] [/A | /B ] source [/A | /B]
[+ source [/A | /B] [+ ...]] [destination [/A | /B]]

source Specifies the file or files to be copied.
/A Indicates an ASCII text file.
/B Indicates a binary file.
destination Specifies the directory and/or filename for the new file(s).
/V Verifies that new files are written correctly.
/N Uses short filename, if available, when copying a file with a
non-8dot3 name.
/Y Suppresses prompting to confirm you want to overwrite an
existing destination file.
/-Y Causes prompting to confirm you want to overwrite an
existing destination file.
/Z Copies networked files in restartable mode.

The switch /Y may be preset in the COPYCMD environment variable.
This may be overridden with /-Y on the command line. Default is
to prompt on overwrites unless COPY command is being executed from
within a batch script.

To append files, specify a single file for destination, but multiple files
for source (using wildcards or file1+file2+file3 format).

Then again, it does go to the trouble of explaining what source and destination are...

The key to get Linux on desktops is to supply it preinstalled on the hardware people buy, at no additional cost.

There's always an additional cost, since the OS has to get there somehow. The fewer computers they have to install it on, the more it costs per computer to do it.

It is time some government looks into the OEM contracts Microsoft has forced on their slaves^W^Whardware vendors.

Well, since the US government forced them to use one contract for all OEMs, I have to wonder how many more governments you want to do this. Thu, 20 Nov 2003 19:27:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Perhaps a Wiki-like documentation system could solve this. A sort of Wikipedia for documentation.

People would have one place to look up information, and if they have something to contribute it would be easy to add a few lines. If you could just hit the "edit" button instead of sending a mail to the developers, asking for permission etc., I think the documentation would improve exponentially Thu, 20 Nov 2003 22:48:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? There are several options for linux documentation. One is google. Another is printed books - there are many by now, on Linux, on everything to installing specific distributions to how to do specific things with it. A third is forums, such as the gentoo forums.
At least with gentoo 1.2 and redhat 6, there were big icons that brought up help by default, on the gui desktop. No typing 'man' or opening a console required.
Most linux projects I've seen have had excellent documentation. There are certainly exceptions. If you learn how to use your package manager, and install documentation packages, you may be pleasently surprised.
Is there out of date information? Yes. It does occasionally bite people.
People don't sit down in front of a computer and know how to use it. My grandmother started using one several years ago, using Windows; things as taken for granted as using the mouse were difficult for her at first, as were concepts such as double or right-clicking. A GUI desktop feels very natural - once you get used to it. This applies to Linux with a desktop environment just as well as Windows or MacOS; I've met Windows users who try linux and immediately like it better (albeit ones at the level of "Where did I lose my window? Did I lose all my work?!" when they minimize.)
I've been using linux for over 4 years. I've not run Windows for about 3 years. I'm happy to admit linux isn't perfect. Judging from the end-user focus of this article, it sounds like the author means application and general environment help; for the vast majority of applications, it is out there. Finding it varies in ease. FWIW, when I used mandrake, it had a link in the 'start/K' menu to tldp.org - it's really not all that hard to find in that case.
There are many reasons people haven't switched to linux. I do not think documentation is a major one. Running into various problems is; finding something different from what they expect is; not having ever heard of linux is; needing an app or wanting to play a game that doesn't run on linux is.
Linux is ready for my desktop. It's ready for my sister's desktop, and my mother's, and some people who work with my dad. It's not ready for people who like the most current FPS, or need specialised apps that don't run on it.
Most home users will not run linux unless it comes pre-installed on their computer. Even if they can use Knoppix, and never have to even install or configure anything, most will not do that much.
Why should people see linux as inheriently better than Windows? It's not... it's got some major advantages, but... so does Windows. I enjoy open source. I enjoy the sense of security that running a linux computer with a kernel that's not vulnerable to any public attacks and runs no public servers brings. I love the documentation - when I was a Windows user, there were far more problems that I just could not solve. I love the price. I prefer gentoo's packaging system to a standard Windows installer, although I'd like it to be more stable, have the ebuilds more debugged, and support binary packages better. I enjoy the huge number of programs that I can just download, including programming languages and interpreters. However, Windows still has better drivers for some hardware, and many programs that don't run on Linux, such as chessmaster 9000; running VMWare isn't really a great solution to that.
There's not a consensus about which distro is best because it's unclear. For someone who just wants to try linux, I'd start by recommending Knoppix. For someone who wants to install it, I'd still say Mandrake; I've had bad experiences with debian, but it would be my second choice. Red Hat got on my nerves, and although their legal stance on things like mp3 was justified, it's a headache for a new user. I like gentoo, but unless someone is patient, has free time, and a fast computer with a fast net connection, I'd never recommend it, despite it being in many ways the best distribution at present, in my view.
Linux is usable by the mainstream. Those with computer experience tend to do ok after "you start by clicking on the K". No, this won't help them do everything; then again, under Windows, knowing to click start won't help you to use RegEdit much.
I agree almost entirely with the author's views of what end-users want; it's why I'm so sure that linux will not be on the majority of home desktops unless it is preinstalled on the majority of home desktops.
I've had the KDE help actually help me.
Want to spend money? Buy a distribution that comes with a support contract. You can do it for less than the cost of a Windows license. Want free help? Learn to find it; even under Windows, it is not obvious that clicking on a question mark will give help, nor is digging under several menus until you find the right one. Every desktop distro of linux which I've used has clear, gui pointers to help, much of which is on the actual system rather than the internet.
Could linux documentation be improved? Absolutely. Should it be? Sure. Is it what's keeping people off linux? In the vast majority of cases, no. Thu, 20 Nov 2003 23:16:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? To those who compare BSD and linux documentation: What on earth do you mean?
The kernel docs of BSD are better. However, this article does not seem to be about kernel documentation or internal kernel APIs. Most userspace apps are - the same as on linux. They have... the same documentation.
To those who say things like "Does the linux community want more users?": you're missing one major point. The linux community has very few, if any, things in common besides personally using linux. I'd be happy to see linux in wider use; I've written documentation, and code, helped newbies, given linux cds to over a dozen people at no charge... but if it never gets a new user, that would not kill me. Would I like to see linux in wider use? Sure... where it makes sense. That's an ever-broadening category; it will never be 100%, but it does keep increasing. It's not in everywhere it makes sense yet.

My pet peeve is the saying that linux is not ready for the desktop. It all depends on what that desktop is used for, and who is using it. For me, it's been ready for the desktop for 4 years; it's made huge advances since then.
Hardware is, for the most part, well supported, win-modems and win-printers aside. My printer works. My scanner works. My network cards work. My graphics cards work, and I have 3d acceleration working on two of the three I've tried to set it up on, although only one also worked under 2.6 for me, so far. There's enough productivity/office software for me; I primarily used abiword for ages, then tried openoffice briefly, and am now semi-happy with TeX. There are more games than I could reasonably play; I like angband varients, frozen-bubble, and klickety. There's a huge number of programming languages; I've been coding small stuff for 5 years, and like to play with new things; having gcc, python, smalltalk, lisp, and functional languages at most an 'emerge' away is great. Firebird is a pretty decent browser; it could be faster and use less RAM, and more stable, and more secure; I've filed bug reports on it. I definately prefer it to Internet Explorer; I hope someday that a lighter and much more secure browser becomes available (one that actually supports modern standards and has optional java, javascript, and plugins, preferably with one-click ways to turn them on/off; dillo and links are ok for minimalism, but less fun.)
Would I have my grandmothers use linux? No. One has never used a computer. The other does a -lot- of geneology, and geneology packages for linux are still far too immature.
On the other hand, several of my cousins use and enjoy linux.
I know it's futile, but I wish people could either accept the best tool for what is being done, or at least take an ideological position like the FSF, but admit it. I hate hearing over-generalisations or people who bash an OS they've never used, whether it's linux or Solaris or MacOS or BeOS or... I also wish people would quit assuming that the linux community is a hive-mind. It's not a corporation; there are divergent goals, and no one has the final say over what programs can be created; at most they can have control over specific projects.
Linux has improved greatly. Knowing what people think is wrong is key to this. The same wrongful assumptions, over and over, and the same topics debated to death 8 years before get tiring.
There are two positive things that I see about this article. One is the number of resources mentioned, and examples of good documentation/good interfaces. The other is the hope that it will inspire someone to improve something. Thu, 20 Nov 2003 23:40:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? A classic example of this occurs in OpenOffice 1.1. Suppose you want to have a page number at the top centre of every page, outside the text area. In another piece of software which shall remain nameless, you select: Insert-Page Numbers, and then follow the window selections. Now try this in Open Office. In desperation you try the Help file to get: Insert- Fields-Page Number, which puts the page number at the start of the text. As far as I can see, there is nothing to show that what you really need to do is create a frame at the top of the page and put the page number field in that frame.

Why couldn't OpenOffice have an actual help entry called "Inserting Page Numbers" and take you through this process in any of the possible ways. So simple once you fight for an hour or so to get to it, but done in less than 30 seconds once you know how.

Oh yes - fully agree - better documentation that tells users what they want to know, not what the writer thinks they should know. Fri, 21 Nov 2003 03:05:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I was looking for answers on the excellent forums at the Gentoo site that would help me through a user error and after searching for an answer for about twenty minutes I got frustrated with the fact that there were still about 300 posts that might apply to my problem and decided to start a new thread wasting the person's time that helped me since the answer was probably already there.

The next morning I had an epiphany. At least I think so, you let me know if this sounds like a good idea.

Why not integrate a troubleshooting format with the forum format. Here's what I mean.

A troubleshooting guide asks questions and as you answer the questions you're led to a probable solution. The problem with troubleshooting is that the information is static and often doesn't apply the the specific problem that you're trying to solve.

A forum is dynamic and able to answer almost any question but much time is wasted either searching for the answer to your question or having the same question answered over and over.

What if you could get into a "troubleforum" or a "forumshooter" where a basic question would get you started like "Is your computer not working?" with a hypertext YES and NO that would lead to the next question like Does it have power? and so on. when the questions finally get narrowed down to the specific problem hopefully there is an answer, if not the user starts a thread and poses a question and the answers are then there for the next person to find.

Think about the possibilities of this idea. You could start a "forumshooter" that dealt with Gentoo and it could grow and connect to other forumshooters, eventually it could turn into a giant network that could answer questions on any topic and is constantly dynamic with new information all of the time. If a programer hates to do documentation he can leave it to the forumshooter (OK, I don't like forumshooter and troubleforum is to mundane. Ideas are welcome.) If someone is having trouble programming their VCR they can find the answer, or they want to know the best organic method of flea prevention it's there. Who knows maybe this will answer the unified field question, or we'll finally come up with the definitive answer on why we're here. Gasp, you could even get answers on how to use Microsoft products.

This would obviously be a big project to organize. You wouldn't want to make everyone start at the most basic question. I can see it now -- Q. Do you think? A. YES (links to) You exist. Q. Does this answer your question? A. NO. (links to) Q. Is your question Cosmological, Psychological, Philosophical, Pragmatic? A. PRAGMATIC (links to) Q. Does this issue involve the Animate or Inanimate? A. INANIMATE (links to) Q. Is this analogy done yet? A. YES.

So there would have to be an infinate number of entry points into the (insert name of project).
Administration would need to be standardized, like HTML or the Uniform Resource Locator, through some sort of organization so when some guy with a web page wants to pose or answer the question - Why do so many things taste like chicken? he can enter his forum into the ever growing network of questions and answers.

Well this should get somebody's brain going if not to improve on the idea at least someone can have fun shooting it down.

LIVE FREE!
Alex Fri, 21 Nov 2003 04:42:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I've never before used page numbering in OpenOffice. I knock out the occasional memo, report, or paper and I'm done. I installed OOo 1.1 a week or two ago to avoid installing the competing virus distribution system on a newly installed PC.
Without hurrying, it took me less than two minutes to create page numbering as described by Dr. Tony Young. No "help", just reading the menus. A header would be the way to put anything at the top of a page. That's a format option. What kind? Page sounds right. Yep, there's Header. So, Format>Page>Header>HeaderOn.
He wants a page number. Insert menu? Fields looks promising. Yep, Page number. So, Insert>Fields>PageNumber.
Ah, he wanted it centered. Block select>Center button. Done.
I'd call the menu system self-documenting, but to Dr. Young's real point, the OOo help system is sufficient. In 30 sec., 'page number' showed me exactly what I did and more. Ditto for headers. If one knows the terminology of a task it's fine. If not, it may take a little longer. Once. Fri, 21 Nov 2003 05:05:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I use Linux exclusively. Slackware to be exact. But, I just got into it around a year ago and I do remember how hard it is initially. After you fumble around a bit compiling this, or configuring that, you begin to get a grasp on the terminology, thus learning how to search for answers. There is sooooo much documentation on my system, I don't know if I'll ever get through it all.

When I spent $200 for Windows XP you know how much documentation I got? NOTHING!!!! I was pretty pissed when I opened up that big box and there was nothing but a folder and a cd in there. Not that I felt a need for a manual for another Windows OS, but come on! $200, and a big ass box to house one cd. There isn't anything on the cd either. No docs, no software, nothing. There is no way I will ever buy another M$ product as long as I live. Hell, you pay the $200 for the OS and it's completely useless until you spend another $1000 on software. You need $100 just to get a decent security suite to half assed lock that POS. I don't have a lot of confidence in a 'one size fits all' security suite to begin with! Let's see... I have 4 menus, with 15 options to choose from. That certainly limits the avenues a cracker needs to explore to find a way on to the 75% of PC's that use Norton this or that.

If you wanna learn *nix, buy a friggin book. Bill Gates never gave anyone a book either. I bought Linux System Administration by Marcel Gagne and it was great. Learned a ton. Fri, 21 Nov 2003 05:44:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I'm a trainer in Telecommunications. The hardest part of all is to be able to think 'dumb'. I mean really dumb.
Problem with most documentation out there is not so much that it's poorly written (a lot of it is...), but it's obfuscated.
The motto I use in training:
"If I knew the answer, I could ask the right question"
springs to mind.

And, please, let's not have the crappy Geek arrogance I encountered in one package somewhere, under the help :-
"I havent the time to write the docs. If you're too dumb to figure it out, stop using it!"
>I figured out if the writer hadn't the time to write the docs, they probably hadn't the time to test it. And as it was a packet-monitoring kit, probably not the time to test it for vulns and exploits either.
# rm -rf packagename
seemed a good choice for the next command. Fri, 21 Nov 2003 06:39:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Well, Barry surely exaggerated in some aspects. But IO guess that was a deliberate act to get us waking up. It's true that there is a lot of documentation out there. But it is also true that it could be improved a lot, that it is often outdated and that we OSS-programmers like coding way more than writing documentation. Windows docs are not necessarily any better *but* that shouldn't be any excuse for us. We are trying to improve our software every day. So why not trying to improve docs as well. If we want the average user to switch from Windows to Linux in fact we *must* be better. Better software *and* better docs. We should take the article for what it is: As a bit exaggerating and in thereby amusing hint into something the OSS-world *sometimes* does not provide yet. Fri, 21 Nov 2003 07:43:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I agree that on some level there is hardly enough good documentation to get you going if you're a newbie. True, this is not true for all areas (I don't find KDE as bad as you suggest). Note that most documentation comes along with your distribution (I find SuSE particularly good). And when you got internet, you can find some nice tutorials (I used one when I connected my scanner) or even ask the developer himself (like I did on some particular use of CDRDAO).

Especially developers packages (compilers, libraries & stuff) can be very badly documented. But hey, some who consider themselves to be technical writers can help (and should help!). There is a free documentation license from GNU. I found the documentation that came along with Forth compilers very bad. Not my own of course, because my 300K sourcecode project comes along with more than 600K of pure text documentation (around 300 pages). Because I wrote a primer for my own compiler I rewrote it for ANS-Forth and release it under a free license. Nowadays it is included with several high profile Forth compilers (some even commercial!), even when I don't consider it to be finished.

You're right to complain. But now DO something about it! Help some geek to write some decent documentation. Linux is free, pay back by doing some work!! Fri, 21 Nov 2003 09:22:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I write open source programs because I want my computer to do certain things for me. I have also realised that if we all share the code that satisfies our personal needs, there will be a lot of free programs out there to reuse. I do *not* write programs to be kind to other people or help them for free. That is just a positive sideeffect.

When you come along and say that *I* should spend some of my spare time to write documentation that *you* need, then I realise that you haven't understood what motivates me to write open source programs. It is not to satisfy other peoples needs, but to satisfy my own, and right now I do not need any documentation.

You can hire me for $70/h if you want me to write any particular documentation. I will gladly help you. Nothing is free, but with the open source model, we only have to pay for it once. Fri, 21 Nov 2003 09:52:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? If the author had bothered going to a bookstore, he would'nt have said that there is a lack of good documentation for Open Source programs. I don't know what he's talking about, considering that Suse or Red Hat manuals (for instance) are better written and thicker than most proprietary software manuals. Heck, in some places, Unix or Linux books are placed right next to Windows items. Fri, 21 Nov 2003 11:46:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Barry, you raised a point which is one of the most important in my opinion, too. I strongly agree with you. This is a key to open source commercial success.

Also some comments complete the picture nicely:

- most users don't read docs; this is sadly true, and that's why the term "documentation" must include the programs themselves; each program/interface should be self-documented and intuitive, but I still see lots of GUIs designed without this in mind, and button labels which can be confusing for a computer expert, too.

- good documentation already exists; this is true in many cases, but is it _organized_? Good documentation must be well organized, consistent and easily accessible and searchable; you cannot tell users to search through tons of howtos just to know how to change the display settings, when they're accustomed to Windows' display properties.

- then there's the localization problem; translation must be done with care, and often it is not, to the point that some users prefer using the original English settings, when they are able to understand them. Also documentation writing is affected by the same sickness; badly written documentation is sometimes worse than no documentation at all.

I really hope to see improvements in this area. Fri, 21 Nov 2003 12:25:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Instead of gracing us with your rant, why don't you roll up your sleeves and write some of this lacking documentation?

Or is that too much like work? Fri, 21 Nov 2003 12:59:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? First off, in response to "Oh, technical writing guru!"
I can guarantee you that he is not enough of an expert in any open source program to be able to write documentation for it. And he would probably need semi-formal training to do so (remember, he's not a programmer), so how about you train him. Or is that too much like work?

The Linux documents are fine... For me... For most of the people here. But that doesn't mean a damn thing. Those docs that are perfectly useful to us are *utterly* useless to a person that knows nothing about computers.

Look, you need the kind of documentation that we find annoying and useless to be able to satisfy Joe Schmoe. You have to start from the perspective that the person kinda sorta knows how to use a mouse and kinda sorta knows how to use a keyboard, and THAT is the COMPLETE extent of the knowledge about what they are using.

Linux cannot and will not be successful on the home desktop until you are able to sit a person down in front of an already installed linux machine (installing linux or windows is really out of the scope of a home user) and they are able to quickly understand and use the system without the use of a manual and especially without your guidance.

Linux needs to be even easier to use than windows! You don't overtake a market by mimicing, you overtake by doing something better.

Until that day comes, linux will have no chance against windows on the home user front. Fri, 21 Nov 2003 14:48:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I never miss the computer section of any book store I visit. Not that I understand half the material, but I still look around. I can't count the number of Red Hat books I've found. Many come with Red Hat installation CD's. At least one was over 1,000 pages. Given the size, it *has* to have answers to most questions that the average/new user is going to have.

I cut my teeth on Red Hat, and I thoroughly recommend it for the curious. Even better, Marcel Gagne's new book comes with KNOPPIX, which means you don't even have to install to harddisk. Is Joe Public so incompetent that a trip to the book store is out of the question? If $200 for XP is a good deal, what's the hang-up about $40 for a Red Hat book that comes with CDs? Why is the onus always on the online documentation?

That rant completed, geek-written docs are written for geeks. Anyone else: good luck. Fri, 21 Nov 2003 15:00:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I will try once again. One mroe time.

-To those who say, it is free so tough luck. I stated in another response that part of my point shows that free program often have beeter documentation than some commercial ones, but that most of both kinds is incomplete.

-To those who say I should do somethign about ti and quit whining. I AM doing something about it. I got you all arguing about it didn't I? And I am trying to help with a documentation project right now, AS WELL AS putting what counts as a large amount of money for me into buying new Linux software (very little of which has adequate documentation).

-To thsoe who say, nyah nyah who cares Windows is worse....so what? That is like a bank robber asking to be turned loose because at least he did not kill anyone. What difference does it make if Windows is worse? Does that make Linux better?

-To those who say fine don't use it. OK, I won't. Fri, 21 Nov 2003 15:58:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? Sorry about the typos. I just got new glasses. Fri, 21 Nov 2003 16:05:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? The author is getting heat because he is answering a question no one here appears to be asking. How can we get OSS acceptance outside the geek community and among normal users?

Also a lot of the heat comes from OSS developers/users who feel all users are just like them.

Guess what, you are more knowledgable then 99% of the market. What meets your needs fails the 99% miserably.

If I ran a software company, I'd arrange for my staff to spend maybe 2-3 hours a week helping newbies at community centers, senior citizen homes etc. I do, and it opened my eyes to the needs of the typical user.

Ordinary users want to stick a CD in, and have it launch and provide them with logical choices, consistent user interface, logical processes, viable alteratives, clear definitions, informative error messages and additional documentation if they want it simply by clicking a button.

This bears repeating :

Linux needs to be even easier to use than windows! You don't overtake a market by mimicing, you overtake by doing something better. Fri, 21 Nov 2003 19:21:00 GMT donotreply@osnews.com (Anonymous) Comments http://www.osnews.com/thread? http://www.osnews.com/thread? I'm working on a license that promotes good documentation for Open Soruce. Here's what I have so far. I don't like vaporware, but I think it's kind of relevant to this discussion.


The Anti-User Hostility Documentation License (AUHDL)

Traditional open-source and free software documentation is meant to deprive an end user of their basic freedom to understand how to get work done with their software. This deprivation of freedom is distilled into a form of oppression, where the only answer to a question born of confusing documentation is "Read The Fine Manual". Further silliness ensues when a world ensconced in 32-bit color and interactive multi-media is eschewed for a world of text-only documentation, whose only attempt at graphic amelioration is pathetic use of more text. We of Clarux feel that the freedom to oppress end-users is not a valid freedom.

It is painfully clear that those who feel it is acceptable to produce documentation that oppresses end-users either through its lack of clarity, lack of examples, or simple lack of existence clearly do not deserve to use, distribute, or take credit for documentation created by those who feel differently. It is the goal of the Anti-User Hostility Documentation License to promote open, accessible, and understandable documentation and thereby create a more open, accessible, and understandable world of technology.

Terms:

1. All documents produced under the AUHDL must have at least three graphic elements. A graphic element is defined as a diagram, drawing, or a computer monitor screenshot. Any modification to a document protected under the AUHDL that reduces the number of graphic elements by less than 3 is prohibited. By July 1, 2005, the requirement for graphic elements will be extended to the use of at least 3 colors. Modification of a document protected under the AUHDL that reduces the number of colors used for graphic elements by less than three is prohibited.

2. While not enforced, it is encouraged that writers of documentation licensed under the AUHDL make their documents accessible to users with visual impairments. It is suggested that authors do not rely solely on the use of the colors to convey relationships, as a significant population has red-green color blindness. It is also suggested that the navigation and display of relationships between pieces of information accommodate blind users.

3. Use of ASCII or Unicode text as a substitute for graphic elements (the practice informally known as "ASCII art") is hereby prohibited from any document protected under the AUHDL. Any modification of an AUHDL document that includes "ASCII art" is expressly prohibited.

4. Any person, company, or entity that wishes to distribute or link to documentation licensed under the AUHDL license must agree not to distribute, link to, or post on the internet the following documentation formats:

a) HOW-TO's.
b) TexInfo
c) Any text-only document.
d) Unix manual pages (aka man pages) Fri, 21 Nov 2003 19:37:00 GMT donotreply@osnews.com (Anonymous) Comments