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