On 15 September 2011 05:24, Heinrich Apfelmus <apfelmus@quantentunnel.de> wrote:

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

_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe