[Haskell-cafe] Categorized Weaknesses from the State of Haskell 2011 Survey
apfelmus at quantentunnel.de
Thu Sep 15 14:24:33 CEST 2011
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
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
A case in point might by my own reactive-banana library.
I have extensive haddocks and many examples ranging from simple to
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.
More information about the Haskell-Cafe