[web-devel] Re: The state of documentation

[Michael Snoyman]

On Fri, Apr 9, 2010 at 8:06 AM, Michael Snoyman <michael at snoyman.com> wrote:

>
>
> On Fri, Apr 9, 2010 at 3:32 AM, Gour <gour at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/web-devel/attachments/20100413/3991d64d/attachment-0001.html