[Haskell-cafe] Categorized Weaknesses from the State of Haskell 2011 Survey

[Heinrich Apfelmus]

Malcolm Wallace wrote:
> In fact, my wish as a library author would be: please tell me what
> you, as a beginner to this library, would like to do with it when you
> first pick it up?  Then perhaps I could write a tutorial that answers
> the questions people actually ask, and tells them how to get the
> stuff done that they want to do.  I have tried writing documentation,
> but it seems that people do not know how to find, or use it.
> Navigating an API you do not know is hard.  I'd like to signpost it
> better.

 From my experience, people are very good at learning patterns from 
examples, so a list of simple examples with increasing difficulty or a 
cookbook-style tutorial work very well. In comparison, learning from 
general descriptions is much harder and usually done by learning from 
examples anyway.


A case in point might by my own reactive-banana library.

   http://haskell.org/haskellwiki/Reactive-banana

I have extensive haddocks and many examples ranging from simple to 
complicated

   http://haskell.org/haskellwiki/Reactive-banana/Examples

but so far, I never wrote a tutorial or introductory documentation. 
Curiously, instead of sending complaints, people send me suggestions and 
code. I interpret this as a sign that my library is easy to understand 
(if you know Applicative Functors, that is) even though a key part of 
the documentation is still missing.


Best regards,
Heinrich Apfelmus

--
http://apfelmus.nfshost.com