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?
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.
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.
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.
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.
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…
..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.
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.
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.
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.
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
As for Mac OS X, what’s not to like about it
Well, let’s start with its GUI “drawers”.
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.
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?
“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…
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!!!
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.
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
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.
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 [i]anything[i] about computers!”.
</endrant>
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.
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.
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
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.
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.
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.
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
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.
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.
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.
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.
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!!
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.
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.
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.
Instead of gracing us with your rant, why don’t you roll up your sleeves and write some of this lacking documentation?
<p>
Or is that too much like work?
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.
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.
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.
Sorry about the typos. I just got new glasses.
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.
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)