On a somewhat related note, I think the Haskell documentation in general is rather patchy and hard to follow for most things. Part of that I think is because of the confusion between the different forms of documentation. In general as a programmer I expect to find three kinds of documentation available, preferably in a centralized location, but at least in a handful of standardized locations. The first kind, is what Haskell has in abundance, and what is hosted in Hackage, which is API documentation. API documentation is written to be terse, to assume you already know how library Foo works (and probably library Bar and Baz too), and you just need to refresh yourself on exactly what the signature of function wibble was exactly. Really good API documentation also fills the role of some of the other kinds of documentation and has some quick examples sprinkled around the most commonly used functions and maybe a nice intro paragraph with even more examples and some suggestions for further information. The second kind of documentation which is very nearly non-existant for most Haskell packages is a user manual that documents in detail all the functions and data types of a package, how you use them, and the ideas and concepts they're based on. Given only this documentation, a firm understanding of the language, and a basic knowledge of the problem domain, anyone should be able to write an application using your library. If they have to spend three hours trying to track down some obscure research paper that's referenced in your documentation a half dozen times in as many functions, you're not providing enough detail and assuming too great a knowledge of the domain. The last kind of documentation which is fortunately somewhat more prevalent then the previous kind is the classic tutorial, which documents and thoroughly explains the most commonly used functions in your library (not to be confused with thoroughly explaining your library which is the job of the user manual). There are quite a few good tutorials on Haskell in general, Monads specifically, and a lot of random bits and pieces floating around on the net, and thankfully collected for reference on the Haskell wiki. On the whole, the Haskell API docs are decent (although most of them are not what I would call "Good"), and the tutorials are also rather plentiful, but the user manuals are practically non-existent. What would be ideal is if the hackage entry for each package also included a link to the user manual for that package if it exists (and hopefully most of them would exist) in addition to the links to the API docs and homepage it already has (I suppose in theory the homepage link can serve this purpose and in some cases it currently does, but an actual "manual" link would be nice). (All of the following were chosen at random) For reference, here is a good example of an API doc: http://hackage.haskell.org/package/zlib Average API docs (but with links to good user manual and tutorial): http://hackage.haskell.org/package/DeepArrow Bad API docs (but once again with a link to average manual/tutorial): http://hackage.haskell.org/package/actor -R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat. On Mon, Oct 12, 2009 at 16:29, John Lato wrote:

...

From: Derek Elkins

On Sun, Oct 11, 2009 at 8:55 AM, Iain Barnett wrote:

...

On 11 Oct 2009, at 13:58, John Lato wrote:

...

For anyone writing introductions to generic programming, take this as a plea from Haskellers everywhere. If one of the RWH authors can't understand how to make use of these techniques, what hope do the rest of us have?

John Lato

P.S. Some might wryly note that I'm the maintainer of a package which is also known for incomprehensible documentation. To which I would reply that our effort is much newer, I consider it a problem, and it's being worked on, contrasted to the state of GP where similarly impenetrable documentation has been and continues to be the norm.

You could say that about most documentation (for Haskell and beyond). Apparently, programmers like programming better than documenting. The

effect

...

of this is that less people use their programming, making their efforts redundant.

Silly really, considering programmers are (allegedly:) intelligent.

Apparently, programmers like programming better than reading as well... in my experience.

I won't disagree. But I think the real difficulty is that the intersection of programmers who can come up with really good ways to solve problems (not even all programmers, unfortunately) and people who are good at writing documentation is vanishingly small.

It seems to me that when someone works in a problem domain (e.g. Generic Programming), they gain a very deep understanding of that area and are used to working at a certain level within it. When introducing the topic to newcomers (even ostensibly smart programmers) the introduction can't assume prior knowledge of the problem domain, but the authors are so used to thinking at one level they often take for granted knowledge that the audience doesn't have.

I don't think this problem is particular to programming, but it is common in Haskell. Most likely because Haskell, with a reputation as a research language, has a lot of computer science types doing research in wide-ranging topics. Somebody's expertise in category theory, for example, might not directly carry over to generic programming (or maybe it does; I'm not an expert in either). _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe