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

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.

Re:i got a better idea...

[mivok]

Isnt that what package managers are for? Have a developer do the 'hard' work of compiling the program and resolving dependencies, shipping it out as a binary package, and letthing the user simply type apt-get install package (granted with rpm systems the user still has to resolve dependencies manually, but most of the ease is there).
Of course, typing any commands in isnt always the most end-user friendly way of doing things.. which explains the existence of the myriad of GUI package management tools.

Personally I like the ports idea of *bsd, donwload a single tar.gz (or use cvs, but we're talking ease of use here), untar it, cd to the correct directory for the package you want to install.. (hmm.. I'm looking to install a networking program, so maybe I should trythe 'net' directory), and just type make install - resolves dependencies, downloads the package, downloads any patches and patches the software for you, configures, compiles, and installs. Presumably gentoo's emerge command works similarly (I havent tried gentoo myself, but anyway).

An user who is just interested in getting the software working and isnt bothered about patching, or having the fastest build for their processor will be perfectly happy with binaries, and if package management tools are still considered too hard, make an installshield style program that leaves one file for the user to run (most linux games I've seen)

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.

Who are you writing your software for?

[ctr2sprt]

If most of your users are having trouble with your current methods, then you need to look at your current methods. Supply binary packages via whatever means necessary. By all means, make the source available too, but understand that 90% of even power users never need or want to see the source for a particular package.

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.

Dumbing down documentation?

[More Karma Than God]

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.