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

[Kyle Murphy]

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 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