[Haskell-cafe] Cal, Clojure, Groovy, Haskell, OCaml, etc.

[Gwern Branwen]

On Tue, Sep 29, 2009 at 3:36 PM, Andrew Coppin
<andrewcoppin at btinternet.com> wrote:
> Tom Tobin wrote:
>>
>> This.  As an experienced Pythonista but a beginning Haskeller, there
>> is *no way* I would have been able to wrap my head around the basics
>> of Haskell without the tutorage of Learn You A Haskell, Real World
>> Haskell, and various smaller tutorials scattered around the Haskell
>> wiki — but I still find the array of libraries confusing (just what
>> comes with GHC — I'm not even talking about Hackage here), since the
>> documentation seems to be quite terse compared to Python's docs.  I'm
>> getting better at reading the code directly, but I'm often at a loss
>> for what a particular library is good for in the first place.  The
>> library documentation seems to assume a mathematical or (advanced)
>> computer science background, and has no problem sending a reader off
>> to see a journal paper for details — not exactly friendly to those who
>> are trying their hardest to unlearn their imperative ways as it is.
>> ;-
>
> While some of the stuff that comes with GHC is quite well documented, others
> are highly under-documented. (As an exercise, go count how many module
> descriptions say "inspired by the paper by XXX at this URL"...)
>
> Admittedly, the System.IO module probably isn't the place to explain what a
> monad is and write a full tutorial on using them. However, look at (say)
> Control.Concurrent.STM.TVar. In my copy (GHC 6.10.3) it lacks even type
> signatures, let alone actual descriptions. Similarly, Parsec has some lovely
> external documentation (unfortunately as a single giant HTML page), but the
> Haddock stuff is bare.
>
> Now, the operative question (and I'm sure we've debated this one before) is:
> how do we fix all this?

As a Wikipedian, my knee-jerk answer is: lower entrance costs!

Specifically, in the past I've tried to think of uses for Gitit beyond
just the normal wiki stuff. One thing I came up with:

- run a Gitit wiki on top of a copy of the base libraries' repos. The
actual Haskell files will be displayed as highlighted articles; eg.
here's a .lisp file displayed nicely: http://gitit.net/sudoku.lisp

People will be able to log in and edit the docs as they please. Every
week or so, the edits could be batched up by some sort of hook and
emailed to the libraries at haskell.org ML; good edits get applied to the
master repo, bad edits get ignored. Another hook periodically deletes
patches that don't make it to the master repo. Thanks to the darcs
backend and per-article editing, we can have the 'wiki' repo (with all
the Front Pages and .conf files one wants for a nice wiki) follow the
'master' repo without running into conflicts.

This is nice enough an idea, but we can go further. Even better would
be haddocks rebuilt on every edit, so users can edit and see the
results immediately*. (You can sort of approximate this locally by
working on files in an editor, keeping a cabal-install looping, and
refreshing in your browser.) I can't guarantee that this would get
people to contribute tips, work-arounds, and examples to the docs, but
it seems much more likely to encourage contributions than our current
quite arcane system of hidden repos and obscure darcs sends to even
more obscure mailing lists.

(Wait, you want me to implement this idea instead of just throwing out
suggestions? Maybe next week...)

* It's not clear to me how to make the built haddocks immediately
accessible to an editor of the .hs page. After all, half the point of
using Gitit is that it can work with the original repo almost as-is. I
have a crazy idea that the Haddock .html can be built and then moved
to Talk:sudoku.lisp, but I've no idea whether this would work. I'm not
sure Talk: pages of non-article files are even possible.

-- 
gwern