[Haskell-cafe] Categorized Weaknesses from the State of Haskell 2011 Survey

[Nick Knowlson]

I think a few examples can go a long way.

I remembered seeing a lot of requests for examples in the results, so I went
back and skimmed the spreadsheet. I found that 11 of the 34 responses under
Library Documentation explicitly called out examples as desirable.

Combined with Heinrich's experience, this sounds pretty promising to me.

Cheers,
Nick

On 15 September 2011 05:24, Heinrich Apfelmus <apfelmus at 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<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<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 at haskell.org
> http://www.haskell.org/**mailman/listinfo/haskell-cafe<http://www.haskell.org/mailman/listinfo/haskell-cafe>
>



-- 
http://nickknowlson.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20110915/a204e081/attachment.htm>