I recognize that Open Source folks are passionate. I understand and I applaud the dedication and fierce loyalty. But for the love of all that is warm and fuzzy, could you please give it a rest? Just for a little while? There is something else that really needs some attention: proper documentation.Editorial Notice: All opinions are those of the author and not necessarily those of osnews.com
I have heard much lately about *Linux_On_The_Desktop*. I read that Linux is finally ready for the desktop. Then I read that Linux is not ready for the desktop yet, but it soon will be. I read that Linux has been ready for the desktop for years. I read that Linux is ready for a few specialized uses, but not ready for the home user. I read that Linux is so easy nowadays that anyone’s grandma can use it. I read that the high level executives in the computer industry themselves can’t cope with setting up their own computers…and then I read about a dachshund in Paducah that managed to install Gentoo unassisted and sent out three emails before his owner caught him.
And always, always, always the discussion comes back to some variation of the following question: “Why aren’t more people using this? Can’t they SEE it is inherently better than MS Windows?”
No. They can’t. And they won’t until a few things change. How can the public at large see anything at all amid this low-hanging cloud of bickering and debate? Suppose an MS Windows end user is considering a switch to Linux, or perhaps just gets curious about trying this newfangled operating system. Where is he supposed to begin? If the experts themselves can’t possibly agree on which one is best for what, how is an innocent newcomer supposed to know what to do?
In order for Open Source software to move out into the mainstream it must first become usable by the mainstream. Is this too difficult to understand? Speaking as a non-programmer end user, a refugee from the tyranny of Microsoft and a reasonably literate person, I am going to tell you something that may shock you. The ugly truth of the matter is….we don’t really care about this stuff.
We have no desire to even know which version of KDE a particular release of a particular flavor of Linux came out with. We don’t know or care which kernel version RedHat uses. We are utterly indifferent as to whether RPM or DEB is a better packaging scheme. The burning question of whether to use XFree86 4.2 or XFree86 4.3 leaves us shrugging. We don’t even care the slightest whit if our computers are using GNU/Linux or GNU/Hurd. In fact, we have no clue about what either one of them really are. The public at large is a hotbed of apathy concerning most of these arguments.
There is one thing however, that we end users do care deeply about. There is an issue that burns in our minds with a searing thirst for knowledge and understanding. There is one question that torments us by day and haunts our sleepless nights. The one question that the public at large cares about is this:
“How in the world am I supposed to make this thing work? Can I have some instructions please? MY KINGDOM for a user manual that I can understand!”
Open Source documentation is terrible. There is no kinder way to put it. Even the commercially distributed software in the Open Source world has substandard documentation. (And believe me, as a technical writer coming from the Windows world, when I tell you that the commercial industrial standards are pretty low). Only a bare handful of Open Source software packages have any documentation at all. And out of the few that do, much of it is either unfinished, inaccurate, or outdated. What counts as explanatory text among geeks would bewilder a nuclear physicist, even a sober one.
Let me pick something at random. I am not trying to make KDE look bad. I personally use KDE almost exclusively, and I love it. But the so-called “help” system….have you looked at that thing? Consider, if you don’t already know what to do, how many people would be able to figure out their solution using just the online help? Really? Just recently I saw someone pointing out how good the documentation for the GIMP is. The GIMP is one of the few packages that can justifiably claim to have user documentation. It is not easy, it is not simple, but it is usable if you keep at it. It assumes, like KDE and most other OSS, a certain minimum level of competence.
This is the key point. Almost all OSS documentation was not written for newbies. It was written by experts for the use of experts. Some of it is surprisingly good. The man pages are a nice example. You open a console, type “man (whatever)” and you get a nice, easy to read explanation. Of course, you must FIRST be aware that man exists, and then you must also be aware that to access the man pages you need to open a console, and then of course you need to be aware of the proper syntax, and naturally you must have a clear idea of exactly what you are looking for and how to spell it….but if you already have gotten that far, the man pages are very helpful.
I have heard all the excuses. Some people claim (with a straight face) that if a program is properly designed it should be self-evident and no documentation should be needed. I have heard the excuse that OSS is still very young, and time is needed to get the documentation up to speed. Problem is, Linux is over ten years old, and some of the other OSS is even older. How long does it take to get started?
Yes, I have seen the Linux Documentation Project. And I ask you, how many newbies know about it? 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. When they don’t see anything resembling documentation, how many new customers are going to be clueful enough to think about searching the net for something called Linux Documentation Project? And even if they stumble over it, how are they supposed to know what to search for?
Not every newcomer to the fold is going to be blessed with a wise and patient sensei to guide their first faltering footsteps along the Way Of The Penguin.
Truth is, most geeks hate to write. They are not good at it, and they know this, and they would rather spend a week in lockdown with 5 large cell mates than write user documentation.
I come before you to plead. I speak for the unwashed masses of non-technical end users who would dearly love to try using OSS, but have no idea HOW. I speak for the clerical staff that keeps getting their work eaten by MS Word. I speak for the accountant that has seen Peachtree lock up their system once too often. I speak for the hapless sales representative whose server just crashed, leaving him stranded 500 miles from headquarters with no way to close the sale. For all of us, I beg.
Can you stop bickering among yourselves long enough to tell us how to run this stuff? In terms we can understand? Please?
Tell you what. I will send you money. Write some usable documentation that lets me buy OSS and get productive with it, but does not require me to become a geek-in-training, and I will send you money. Lots of money. I will BUY your product. How’s that? Could you get a better offer anywhere?
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?”
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.
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.
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
If you are such a good windows technical writer: please start to write for OSS
We can use it!
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.
“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.
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.
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 …
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.
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.
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.
“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.
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.
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.
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.
There are already hackneyed responses to the editorial: “My OS has good docs” “Nobody reads it” “You’re an a**” to paraphrase a few. <Sigh>
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.
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.
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.
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?
Heard once in a land, far, far away: Read The Source, Luke!
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.
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.
@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.
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.
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.
Google it.
From Post #7:
“…F) Pay for a distro and use the support your entitled to…”
Nice one.
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.
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.
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.
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.
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.
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/
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
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.
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…)
> 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).
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.
http://www.tldp.org/
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.?
I can’t believe some of the ignorance I see in the comments. People say “dude just apt-get <something>” 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 <project name here>” 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.
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.
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.
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.
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.
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.
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.
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.
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 http://www.debian.org or http://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
Correction: in “net use sharename /delete”, there is a forward slash in front of “delete” (it didn’t display for some reason).
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/
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.
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.
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
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.
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.
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.
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 slow
`
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.
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.
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)
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.
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
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.
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.
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.
“……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.
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!
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.
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.
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….
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.
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”.
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?
”
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?
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.
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
I think the idea of Open Source is pretty good.
But we need more new ideas to improve the development.
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”.
“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
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.
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.
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.
Try starting with the KDE docs http://docs.kde.org/
Many of those help files are either half-done or entirely useless.
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!
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.
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.
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
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
).
Nope, Unix System Resources
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(?!) <cough>QuickReports<cough> 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!)
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 http://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!
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?
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?
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.
“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
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. 😉
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.
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é
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 http://www.pclinuxonline.com and http://www.mandrakeuser.org