[Haskell-cafe] Sparse documentation

Simon Peyton-Jones simonpj at microsoft.com
Wed Jul 4 03:09:49 EDT 2007


Writing documentation for libraries is one way in which ordinary Haskell users can really contribute to the Haskell community.  It's not hard to do (grab the Darcs repo, type away), and it's widely appreciated.

People often don't feel "qualified" do to this, but documentation written by an intelligent but "unqualified" person (perhaps including "not sure what happens here") is a lot more useful than no documentation at all.  Yes I know that misleading documentation can be a Bad Thing but I think lack of documentation is a much bigger problem than misleading documentation, as of today.

Simon

From: haskell-cafe-bounces at haskell.org [mailto:haskell-cafe-bounces at haskell.org] On Behalf Of Brent Yorgey
Sent: 03 July 2007 22:09
To: Andrew Coppin
Cc: haskell-cafe at haskell.org
Subject: Re: [Haskell-cafe] Sparse documentation


It's also nice to have some brief comments in the API docs to say what
the heck a particular module is even *for*, and provide enough info on
the stuff in that module that you can quickly dip into it when you can't
remember the name of something...

I certainly don't disagree with you!  I was just commenting on the tendency of the community to document things in academic papers.  But I'm glad to hear from Duncan that better Haddock documentation will be in the next version of the libraries.

After many hours tying my brain in knots, I *think* I need to use a
monad transformer... but I've never ever done that before. So I'd like
to learn how it works.

Try http://uebb.cs.tu-berlin.de/~magr/pub/Transformers.en.html.  I found that paper very clear and helpful in learning to use monad transformers.  Then you will probably also want to read http://cale.yi.org/index.php/How_To_Use_Monad_Transformers.

-Brent

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/haskell-cafe/attachments/20070704/eb83b4b6/attachment.htm


More information about the Haskell-Cafe mailing list