On Sat, Oct 31, 2009 at 18:39:45 +1100, Trent W. Buck wrote: > >> - Went down a dead-end by misreading the build-it-yourself instructions at > >> <http://www.darcs.net/manual/node8.html>. Looked at Setup, figured out that > >> it's not a shell script, but rather Haskell. > > > > Anything we can do to improve this? > > It looks pretty straightforward to me. I don't know why the OP thought > Setup would be a shell script, or why it would matter that it wasn't.
OK, so I don't think it's worth spending too much energy on this, so excuse me for blathering on about it! I mentioned the eyes glazing over effect earlier: we say all the right things (and even go so far as to call it "The Easy Way" vs "The Hard Way"; but *still* people miss them because they tend to skim. I think part of the problem is that the Hard Way takes more steps, so it's got longer and thereby more visible. Perhaps one way is to cope with it is to squirrel away the long list of dependencies in some other file and tell users to go look there. Don't know if that will be a maintenance nightmare in the long run though. Is it really necessary to have them at all? > > Great. One thing I do is to just download the Haskell Platform > > via http://hackage.haskell.org/platform/ > > Is it worth mentioning haskell-platform in the node8 page? Another effect we may be running into (pure speculation) is "oh, I don't know what cabal-install is, so I'll try this thing below that looks recognisable (I just have to run a program called Setup)". Again, we already say the right things ("this will track dependencies for you"). SO maybe we can block that laziness effect by saying "ah, if you don't know what cabal-install is, the easiest way to get it is by installing the Haskell Platform". Finally another thought is that we could slightly water down the recommendation to just use a binary. I tend to find that once I've got the Haskell Platform, installing darcs is quite easy. The motivation behind this watering down would be to avoid making the Easy Way look hard (which may then strengthen its position wrt Hard Way). Thanks! PS. In the interests of KISS, I guess I wouldn't worry too much about this eyes-glazing-over effect; I guess working too hard to try and *guess* how users would react to blocks of text would just lead to lots of second-guessing and crazy contortions. -- Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow> PGP Key ID: 08AC04F9
pgpvn4NedaY0B.pgp
Description: PGP signature
_______________________________________________ darcs-users mailing list [email protected] http://lists.osuosl.org/mailman/listinfo/darcs-users
