On Tue, Apr 13, 2010 at 12:54 PM, Michael Snoyman <
michael@snoyman.com> wrote:
>
>
> On Fri, Apr 9, 2010 at 8:06 AM, Michael Snoyman <
michael@snoyman.com> wrote:
>>
>>
>> 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?"
>>
> So I finally decided to start on the documentation front. Thanks to everyone
> who's kicked me to get it done, and thanks in particular to Gour for
> reviewing some of it for me. I'll be placing on Yesod-related documentation
> on a new site:
>
http://docs.yesodweb.com/
> I'm using Hakyll to generate the site, which is working very nicely. The
> code is all available on github (
http://github.com/snoyberg/yesoddocs), so
> if anyone wants to make changes, you can either e-mail me or send a patch.
> It's not *quite* as nice as a wiki for collaboration, but hopefully will be
> easier to follow.
> Next goal will be to put up docs on web-routes-quasi.
> Michael