On Fri, 9 Apr 2010 08:06:08 -0700
"Michael" == Michael Snoyman wrote:
Michael> I can't speak for others, but I personally don't have a Michael> problem investing in documentation on my one-man-show Michael> libraries. In the specific case of Yesod, I *know* it's going Michael> to have some major changes in the next release, so it's not Michael> worth it right now. OK. Let's wait that Yesod becomes more mature, then we'll evaluate it again. Michael> In general, I think the problem for library writers is that- Michael> since *we* wrote the code- we don't know what's confusing Michael> about it. Well, I agree it's not easy to put ineself in another's shoes, but here lies the difference. ;) Michael> As far as we're concerned, our code is beautiful, elegant, Michael> simple and self-documenting (until we look at it again six Michael> months later). :-) Michael> We really need an outside voice to tell us what's lacking. Simple tutorials to get us going. Have you seen the Django tutorial written in several parts? Michael> So instead of saying "fizzbuzz has no documentation," maybe Michael> say "I saw the fizzbuzz tutorial on creating foobars, but I Michael> couldn't figure out how to extend that for wibbles. Could you Michael> write a tutorial for that?" Well, at the moment I am playing with Hakyll and can just recommend every library writer to check Hakyll's tutorials at http://jaspervdj.be/hakyll/tutorials.html Psychologically it is very encouraging to be provided with few simple steps and achieve something instead of starring at the Haddock-generated docs only. Even the Haskell language (which is not at all simple) has "Haskell in 5 steps" & "Learn Haskell in 10 minutes" tutorials. One may say it's kind of cheating, but if the easy introductory material sparks enough interest in the noob user, there is good chance that he/she will investigate further. Sincerely, Gour -- Gour | Hlapicina, Croatia | GPG key: F96FF5F6 ----------------------------------------------------------------