<br><br><div class="gmail_quote">On Fri, Apr 9, 2010 at 8:06 AM, Michael Snoyman <span dir="ltr"><<a href="mailto:michael@snoyman.com">michael@snoyman.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<br><br><div class="gmail_quote"><div class="im">On Fri, Apr 9, 2010 at 3:32 AM, Gour <span dir="ltr"><<a href="mailto:gour@gour-nitai.com" target="_blank">gour@gour-nitai.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
On Fri, 9 Apr 2010 08:36:51 +0200<br>
>>>>>> "Simon" == Simon Hengel wrote:<br>
<br>
Simon> My feeling is that we lack mostly short, tutorial-style<br>
Simon> introductions, that just get you started with a topic/library.<br>
<br>
I agree.<br>
<br>
Moreover, practically every 'framework' (except Happs) is more or less<br>
one-man show band, i.e. it works for their authors without docs, but<br>
that's not the way one can build community around it...And without<br>
some 'critical' mass of users, one is reluctant to invest time/energy<br>
into such products...Kind a catch-22. :-(<br>
<br>
<br></blockquote></div><div>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.</div>
<div><br></div><div>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.</div>
<div><br></div><div>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?"</div>
<div><br></div><font color="#888888"><div><font class="Apple-style-span" color="#000000"><font class="Apple-style-span" color="#888888"><br></font></font></div></font></div></blockquote><div>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:</div>
<div><br></div><div><a href="http://docs.yesodweb.com/">http://docs.yesodweb.com/</a></div><div><br></div><div>I'm using Hakyll to generate the site, which is working very nicely. The code is all available on github (<a href="http://github.com/snoyberg/yesoddocs">http://github.com/snoyberg/yesoddocs</a>), 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.</div>
<div><br></div><div>Next goal will be to put up docs on web-routes-quasi.</div><div><br></div><div>Michael</div></div>