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
