Slashdot Mirror
Open Source for Dummies?
GNUpowerSoul asks: "I have been working for several years on a large open source library. Ever since we made our first public release three years ago, we have found that the majority of our users seem to have no experience whatsoever with open source ideas and conventions. We have had to dumb down our documentation considerably (to the point where we have multiple pages to describe in excruciating detail the usual 'configure; make; make install' step). Has anyone else had experience in how to deal with a user community who doesn't understand the 'normal' practices for open source projects?"
Sounds like your users have problems with Unix, not "open source" per se. I'm not sure how to familiarize people with Unixisms. There was no manual that said "here is how to compile and install stuff" (well, besides the INSTALL file!!). I learned by doing.
It's 10 PM. Do you know if you're un-American?
get rid of the ./configure, make, make install, and change it to a simple "install" script that handles all those tasks automagically.
I am an experienced PC user (from 95% windows / dos background), and a sysadmin if a fairly large company. I am mostly self-learned, and the main difficulty I have with open source - linux is that most instructions assume a level of knowledge that I dont have, so I end up getting frusterated and dropping the project. Like, I am trying to get sendmail configured to act as an intermediary between our exchange server and the web, and filter out content. Well I have found some helpful guides, they all say something like 'compile sendmail' and I'm stuck not knowing HOW! I do phone support, and 90 percent of the time I just rattle off..
:)
'click start' then click settings' and click on the control panel... well, start is the button in the lower left that says 'start'... no, its not a button on your PC, its on the screen... yes, I am sure its not a button on the front of your computer...
Anyways, you get the idea. Make it simple, or at least someone out there make a basic guide on things that most instructions take for granted!
No I didnt spell check this post...
'configure; make; make install' isn't unique to open source, it's unique to *nixes. Ye olde open source Windows program doesn't take it, for example.
So if your problem is really 'How do I teach newbies to compile on a *nix platform?', then I would recommend, say, Building and Installing Software Packages for Linux.
On the other hand, there's the ever-so-popular 'RTFM', or the only slightly less popular 'no response', both of which have a long history in open source.
Well, I've been doing libraries for Windows which users can use when they want to install network drivers and stuff like that. It basically does all the configuration there is to do. Documenting library API felt really stupid. Function names was so self-explanatory (config_ip_setting, bind_interface_to, and so on...). Even the guys who used that library was very skilled programmers but for some curious reason I had to document stuff like "Function: config_ip_settings Descript: Makes IP setting configuration." Oh well...
You don't know what you don't know.
Get volunteers to make packages for at least recent Red Hat, Mandrake and Suse. A lot of newbie installs won't have the development tools installed, which is sure to confuse them when they're trying to follow your instructions for compiling.
What I'm listening to now on Pandora...
The usual 'configure; make; make install' step should not exist! This is the single most awful thing about Linux. God help the user that has a dependency problem.
Binaries should just slide on in. At worst your install program should do any voodoo required.
Ready to be modded into oblivian now,
Bill (who started on V7 Unix thank you very much)
bamph
If you're users are that stupid/unnerds, maybe you should be dealing with binaries, and leave the source code for people that care about it.
...and the result is fink.
Really, the situation you describe is very similar to what the oldtime Mac-heads who like OS X are going through. For many examples of how to boil down these kinds of instructions, see Mac OS X hints.
Basically: KISS. Like, three commands for one concept? How would you like to open an application by clicking it, dragging it to another location, and then clicking it again?
--
$tar -xvf
GNU software installation procedures are the least user-friendly of all those I've used. They generally go like this:
./configure
./configure
./configure
./configure;make;make install recursions.
Download software.
Search for documentation - find incomplete and poorly written docs that assume too much.
research and correct 15 badly documented error conditions.
identify 3 totally undocumented errors.
join project mailing list and post question.
be roundly flamed and referred to FAQ
post references showing errors are not documented in FAQ
be roundly flamed and referred to list archives
search list archives for several days
post again asking for specific references to archives
Acerbic but kindly guru finds comment written in swahili that is only in the CVS version you can't access, and translates it for you in a private Email.
remove a single character from the configure script
edit the makefile to correct unwarranted assumptions about file locations, system capabilities, network architecture, etc.
make
correct typos introduced by prior editing (D'OH!)
make
research and correct 7 errors caused by missing libaries (these libraries are normally required only by Welsh Morris dancers, but for some reason your GNU software won't compile without them).
make
research and attempt to correct 3 errors caused by having a different version of gcc than the software authors.
make
give up on correcting the errors and go download the precise version of gcc used by the developers.
make
cheer like nobody's watching, which they aren't because it is five O'clock in the morning.
make install
Congratulations! You have sucessfully built your GNU software. This amazingly powerful software will now run incredibly smoothly and accurately for unbelievable lengths of time. (Unless it's a 2.4 linux kernel, in which case it'll be obsolete by Monday when the latest remote root exploit comes out, or whenever Linus decides to replace a major subsystem wholesale in the middle of a "stable" kernel series.)
After a few years of living comfortably with your smoothly running, reliable, low maintenance GNU software, you'll break even on the pain and suffering quotient.
I recently configured heartbeat and I've done most of the uber-GNU utilities that don't deign to have man pages (info is so much better, the only way it could be more user friendly is if it required all input in Common Lisp) so it's just barely possible I might have some idea what I'm talking about. On the other claw, I may be stark raving bonkers from too many
I recommend giving each user a report 60 pages in length, and on pages 28, 29, 30 and 31 print in enormous letters:
R T F M
Then after they have digested this report, introduce them to the delights of man. :)
The single most important concept in Unix is that there is ONE TOOL for every TASK. The "users" you refer to (hopefully we're talking about administrators) think that "compile and install program" is one task.
For Open Source programs that one has to compile, there are actually three tasks: configure, build, and install. For closed-source software, you have already paid someone else to perform the first two tasks for you, and lost quite a bit in terms of configurability in the process.
With Open Source, you get to control everything from configuration to compilation to installation. The downside to this flexibility is that for poorly-maintained projects, it doesn't always work. Separating the process into three distinct steps can also help the administrator to diagnose problems with the install.
"I assumed blithely that there were no elves out there in the darkness"
b
testing out my trending skills
Provide binaries for major platforms, and all compilation issues will vanish.
If this is not an option, and the install process is really that complex, and your users are really that dumb, and are unwilling to RATFM (All Those Manuals) -- why don't you provide some hand-holding services and have them pay for it?
I meant to say that every TOOL performs only ONE TASK. It really should be repeated around here more often, because I still (obviously) haven't heard it enough :)
"I assumed blithely that there were no elves out there in the darkness"
He made some excellent points, primarily knowing
how to use an OS is not the same as using a computer
and sendmail is not designed for point, click, install, running.
It is a mess and tough to do (even after I've read the book).
This is a bit of a problem for open source, because most open source developers don't really think about end users (and if they do, think about them as "lusers"). And if they do, they tend to think the end users are as smart and experienced as they are, which is seldom true. So open source programs tend to get written for, well, programmers. If they work for other people too, that's viewed more as an added bonus that a requirement. I'm not mentioning this simply as a rant, but because you may be suffering from this yourself. And, more constructively, thinking about your program as a whole in this way may help you to improve it even more by making it useful to an even wider array of people.
My lecture from the Haifa GNU/Linux Club talks about basic administration of GNU/Linux boxes. Check out the entire "Welcome to Linux" series, which includes several other lectures.
In addition to that, the Haifa GNU/Linux club has made many lectures about various subjects, all available online.
Make even shorter URLs - 8LN.org
You've just discovered that the people wanting to use your resource arn't the same people you expected to want to use your resource.
Creating documentation to meet the needs of your users is educating your users, it isn't dumbing anything down.
Go here to create your own Slashdot dis
Have a developer do the 'hard' work of compiling the program and resolving dependencies, shipping it out as a binary package
For a small operation, renting HTTP[1] server space to hold binaries for 20 different platforms can be prohibitively expensive unless the application is designed to run only on Microsoft Windows operating systems on x86 computers.
Will I retire or break 10K?
Any problems after you install without referring to the stuff that comes with says one of two things:
So how do you handle those people who do read the READMEs, FAQs, and HOWTOs but fail miserably to understand them?
Will I retire or break 10K?
Then how do you respond to support requests containing
(I Did Not Understand The Intercourse-having Manual)?
Will I retire or break 10K?
I can't figure this out. Why does source code need to be "configured" anyway? Can't you write your program in ANSI or POSIX C? Are you too lazy to write your own makefile? (I think Make is a piece of crap, but that's a subject for another rant...)
A web page for one program (Microwindows, I think) crowed about using 'configure' to make itself more portable. I laughed out loud at that. To run 'configure', you need many megabytes of ported UNIX tools installed -- not to actually compile or run the code, but just to "configure" it! Not my idea of portable...