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 <jwlato@gmail.com> wrote:
> From: Derek Elkins <derek.a.elkins@gmail.com>
>
> On Sun, Oct 11, 2009 at 8:55 AM, Iain Barnett <iainspeed@gmail.com> 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