[Haskell-cafe] Re: Documentation (was: ANN: text 0.5, a major revision of the Unicode text library)

Kyle Murphy orclev at gmail.com
Mon Oct 19 17:32:35 EDT 2009

On a somewhat related note, I think the Haskell documentation in general is
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
I expect to find three kinds of documentation available, preferably in a
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
API documentation is written to be terse, to assume you already know how
Foo works (and probably library Bar and Baz too), and you just need to
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
and has some quick examples sprinkled around the most commonly used
and maybe a nice intro paragraph with even more examples and some
for further information. The second kind of documentation which is very
non-existant for most Haskell packages is a user manual that documents in
all the functions and data types of a package, how you use them, and the
and concepts they're based on. Given only this documentation, a firm
of the language, and a basic knowledge of the problem domain, anyone should
able to write an application using your library. If they have to spend three
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
of documentation which is fortunately somewhat more prevalent then the
kind is the classic tutorial, which documents and thoroughly explains the
commonly used functions in your library (not to be confused with thoroughly
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

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
homepage it already has (I suppose in theory the homepage link can serve
purpose and in some cases it currently does, but an actual "manual" link
would be

(All of the following were chosen at random)

For reference, here is a good example of an API doc:

Average API docs (but with links to good user manual and tutorial):

Bad API docs (but once again with a link to average manual/tutorial):

-R. Kyle Murphy
Curiosity was framed, Ignorance killed the cat.

On Mon, Oct 12, 2009 at 16:29, John Lato <jwlato at gmail.com> wrote:

> > From: Derek Elkins <derek.a.elkins at gmail.com>
> >
> > On Sun, Oct 11, 2009 at 8:55 AM, Iain Barnett <iainspeed at 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 at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/haskell-cafe/attachments/20091019/28884eb2/attachment.html

More information about the Haskell-Cafe mailing list