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