On Fri, 2007-27-04 at 13:09 +0100, Robin Green wrote: 
> But just think about it... is it easier to DOCUMENT the problem or
> just include a workaround in the make install code?



It's easier to document the problem.

For the individual developer it is easier to document the problem.  For the development community as a whole it is easier if individual developers fix problems or at least make them more easily spotted than obscure notes in gigantic README files.

For the individual developer it takes, hypothetically, two minutes to add a note to the effect that an out-of-date version of libreadline is required while it may take ten minutes to add a check to the configure script (and test it!) and even a day to fix the problem to work with the current version of libreadline.  So yes, it is easier to document.  By far.

But now broaden the scope to the community.  The compiler is downloaded.  The process of building it begins.  (It does take a long time to build GHC...)  The user waits that long time and ... the build fails.  Now s/he has to search through output whose error messages are not exactly the most friendly in the world.  Typically, for example, you're about five levels deep into make and the error message that actually tells you what's wrong is in backscroll.  So you find that message and slap your forehead.  Doh!  You download and install your old version of libreadline and try again.  Time wasted?  Ten minutes at least.  More likely half an hour.  Lather.  Rinse.  Repeat.  (There are probably other dependencies to outdated packages, after all.)

OK, let's go the RTFM route.  Each and every developer reads each and every README file in each and every project combing it for references to bizarre dependencies.  Let's be hyper-generous and say that each developer only spends one minute on the README file; that the README files in question are a paragon of informational organisation (instead of the more usual data dump in no particular order).  Let's further suggest that it takes only five minutes to get all the unexpected dependencies worked out, downloaded and compiled/installed.  Total time to make up the fix?  Six minutes.

That one minute to find the information in the README file is far shorter than the time it would take to add the equivalent logic to the configure script.  So if you have one to nine end-users, the net time wasted to document instead of modifying the configure script is less.  But I think that GHC has quite a few more than nine end-users.  The aggregate time wasted in the community (without even factoring in the time required to compile/install the desired version of libreadline) suddenly becomes much higher than the time saved by not writing that configure script modification.  Indeed I suspect that the aggregate time wasted would be sufficient to justify the modification of the code to support the latest version of libreadline in the first place once you factor in the time wasted compiling/installing the correct libreadline version.

Now what relevance does any of this have to the individual developer?  Why would s/he care about the end-user experience?  Well, let us not forget that said individual developer is part of that overall community.  That said individual developer faces exactly the same wastes of time poring over README files (or, more likely, bizarre build errors) to figure out how to get the tools they use to compile.  That said developer, too, would be more productive individually, not to mention the community as a whole, if the majority of the development community's members were to fix problems rather than documenting them.

Virtually no other open source project does this, in my experience.

So why not be the first?  Why not be better than the Other Guys<tm>?

--
Michael T. Richter <ttmrichter@gmail.com> (GoogleTalk: ttmrichter@gmail.com)
I'm not schooled in the science of human factors, but I suspect surprise is not an element of a robust user interface. (Chip Rosenthal)