[web-devel] Re: The state of documentation

[Michael Snoyman]

I'm torn on this one. I'm not going to bother retroactively doing
documentation for 0.0.0; however, once I release 0.2.0, and I work on 0.4.0,
I'd like people to have access to documentation on released code as well as
development code. I'm not quite certain...

As far as that intro page, I was providing that table more as a comparison,
but I think I'll be removing it entirely.

Michael

On Tue, Apr 13, 2010 at 1:18 PM, Thomas Hartman <
thomashartman1 at googlemail.com> wrote:

> It looks great.
>
> My only possible nit is that it seems odd to include docu for 0.0.0 as
> well as 0.0.2, why not just do the latest and let the past be done?
>
> On Tue, Apr 13, 2010 at 12:54 PM, Michael Snoyman <michael at snoyman.com>
> wrote:
> >
> >
> > 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
> > _______________________________________________
> > web-devel mailing list
> > web-devel at haskell.org
> > http://www.haskell.org/mailman/listinfo/web-devel
> >
> >
>
>
>
> --
> Need somewhere to put your code? http://patch-tag.com
> Want to build a webapp? http://happstack.com
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/web-devel/attachments/20100413/6ab603b1/attachment.html