[Haskell-cafe] Re: poll: how can we help you contribute to darcs?

[Adrian Hey]

Brandon S. Allbery KF8NH wrote:
> (Hm, I feel a blog rant coming on.)

I take it you mean as the perfect example of how to kill off interest in
your own project :-) I can't help thinking this was so obviously going
to happen that it must have been Davids intent at the time he wrote
that announcement. The only doubt I have is whether he was just in a
grumpy mood at the time and now regrets this, or whether he still feels
this way.

To answer the OP's question, when I first looked at darcs I was quite
enthusastic about it and did indeed consider hacking on it. But a few
hours browsing the source code made me realise I would never be able to
do this easily because of the lack of decent documentation of source. It
was "literate" haskell (which I dislike anyway) and the literate
commentation that I could see told me practically nothing about the code
I was actually looking at. Instead it was just the markup that would
eventually become the user guide (presumably). So as well as having no
useful documentation (for a would be contributor) I had make the extra
mental effort deliberately avoiding reading the distacting and utterly
irrelevant literate commentation clutter. It would have been easier if
there was no comments at all.

The net result was that I couldn't even figure out what the various
functions I was looking at were trying to do (and hence whether of not
they might be the source of the bug or performance bottleneck or
whatever). Put simply, (as someone else observed earlier) it seemed to
me like it was written and organised so as to be unmaintainable by
anyone other than David himself. That said, I think by normal the
standards of OS projects darcs *user* documentation is very good,
but for would be hackers this is not enough (decent source
documentation is needed too IMO).

I also think Neils idea of breaking darcs up from 1 monolithic prog
to a darcs lib suite is a good idea. This would give decent haddock
documentation for most of the code base and an easy way to have
multiple user interfaces (gui/web/command line based).

Regards
--
Adrian Hey