[web-devel] Re: The state of documentation

[Michael Snoyman]

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?"

Michael
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/web-devel/attachments/20100409/46ead111/attachment.html