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?"

Comments

One good example...

[kawika]

Has anyone else had experience in how to deal with a user community who doesn't understand the 'normal' practices for open source projects?"

These guys have had a lot of experience. Notice how much work they put into documenting even the bugs.

Unix

[Hard_Code]

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.

i got a better idea...

[Anonymous Coward]

get rid of the ./configure, make, make install, and change it to a simple "install" script that handles all those tasks automagically.

Re:i got a better idea...

[renehollan]

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?"

WHOA!

Users and 'configure; make; make install' do not go together. Unless, of course, by "user", you mean a developer foriegn to open source conventions. This would most likely include non-Unix developers.

While it is appropriate for users to compile and install their own open source software, like the parent points out, this should happen automagically for them: insert CDROM, click "OK", watch it compile and install (or not and offer to email the build log to the development team).

If your audience are developers not familliar with open source conventions (and, by extention important licenses like the GPL), then, yes, technical things like "here's the standard way to build" a package should not faze them (unless, perhaps their microSofties that have never seen the outside of Developer Studio.

OK, here is my problem

[override11]

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! :)

Re:OK, here is my problem

[__past__]

I am trying to get sendmail configured

Here is your fundamental mistake: Sendmail is not indented to be configured by humans. The format of sendmail.cf is optimized for bored ancient nordic gods that love puzzles, not for people trying to get a job done.

NEWSFLASH!

[mildness]

It's not the users that are clueless it's the architecture.

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)

Yup, it's a GNUish Unixism....

[Ashurbanipal]

GNU software installation procedures are the least user-friendly of all those I've used. They generally go like this:

Download software.
Search for documentation - find incomplete and poorly written docs that assume too much.
./configure
research and correct 15 badly documented error conditions.
./configure
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
./configure
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 ./configure;make;make install recursions.

Nope, It's the Users...

[benjamindees]

And I know, because I was one at one time.

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.