On Fri, Apr 9, 2010 at 3:32 AM, Gour <gour@gour-nitai.com> wrote:

On Fri, 9 Apr 2010 08:36:51 +0200
>>>>>> "Simon" == Simon Hengel wrote:

Simon> My feeling is that we lack mostly short, tutorial-style
Simon> introductions, that just get you started with a topic/library.

I agree.

Moreover, practically every 'framework' (except Happs) is more or less
one-man show band, i.e. it works for their authors without docs, but
that's not the way one can build community around it...And without
some 'critical' mass of users, one is reluctant to invest time/energy
into such products...Kind a catch-22. :-(

I can't speak for others, but I personally don't have a problem investing in documentation on my one-man-show libraries. In the specific case of Yesod, I *know* it's going to have some major changes in the next release, so it's not worth it right now.

In general, I think the problem for library writers is that- since *we* wrote the code- we don't know what's confusing about it. As far as we're concerned, our code is beautiful, elegant, simple and self-documenting (until we look at it again six months later). We really need an outside voice to tell us what's lacking.

So instead of saying "fizzbuzz has no documentation," maybe say "I saw the fizzbuzz tutorial on creating foobars, but I couldn't figure out how to extend that for wibbles. Could you write a tutorial for that?"