I'm definitely interested in Yesod, and it's currently at the top of my rather short list of possibilities, but the relatively immaturity does worry me a bit, in particular as it pertains to my fourth requirement. I'm not opposed to making updates from time to time to keep the site current with the latest release, but I want to avoid having to constantly tweak things, and most importantly I don't want to end up in the situation where a year or two down the line the entire framework gets deprecated and I essentially endup having to re-write the entire site from scratch. I should probably stress that I'm a relatively newbie to Haskell, and there's still a few things that I'm trying to get my head around. In particular I haven't had much chance to really look at TH, and my understanding of monads is a bit rocky in places although I've got the basic principle worked out. I'm further hampered in that I'm working on this project and other Haskell related things in my spair time which is rather lacking at the moment, so ease of understanding (I.E. good documentation) is a major bonus for me. For persistance I'm not all that worried as I can just use one of the HSQL packages and one of the various SQL servers, although any support in the framework itself would be welcome. Near as I can tell, the options for doing websites with Haskell can be boiled down to: 1) Happs(tack) 2) Yesod 3) Roll your own from low level components and at least in the case of Yesod there's still a few components that are essentially roll-your-own, although I should point out I'm not opposed to that assuming there's some good examples available of exactly how to go about doing that. In particular I've been looking over the bug tracker and blog code based on Yesod. -R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat. On Wed, Apr 7, 2010 at 13:25, Michael Snoyman wrote:

Hi Kyle,

Well, the web-routes-quasi package is basically an attempt to split out the quasi-quoting used in Yesod so that others can use it. The next release of Yesod will in fact depend on web-routes-quasi (in all likelihood).

The documentation on Yesod *is* sparse at the moment, mostly because the API is still immature and will have some major changes over the next few releases. If you're looking for something that will have backwards compatibility, Yesod is not for you at the moment.

I will say that I use Yesod in production on a number of websites, and it's worked well enough for me. One thing that it is majorly lacking is a persistence layer, but I'm working on that[1]. I also have been toying with the idea of replacing HStringTemplate with a type-safe templating system[2]; for fun I'm basing the syntax off of Haml[3]. If you want information on either of these projects, or have suggestions, I'd love to hear them.

If you have other concerns, I'm also interested in hearing them. Yesod is young and has plenty of room to grow, but I think it's a pleasure to program with and is filling a niche that is missed by other Haskell packages.

Michael

[1] http://github.com/snoyberg/persistent [2] http://github.com/snoyberg/hamlet [3] http://haml-lang.com/

On Wed, Apr 7, 2010 at 10:46 AM, Kyle Murphy wrote:

...

I'm looking at experimenting with developing a site and due to various constraints I'm considering using one of the haskell frameworks. I experimented a bit with Happstack, although I'm not all that happy with it and I'm interested in alternatives. I've also looked briefly at yesod but it doesn't seem to be very well documented and I've got some concerns. The environment I'm working in has constrained memory, about 300M physical, with a further 500M of swap, but a relatively beefy CPU, so I'm trying to stay away from any of the in memory systems like MACID in happstack. At this point I'm mostly toying with the different frameworks to try to get a feel for them, but in a couple months I'm probably going to need to actually put together a production system that can handle some fairly low duty e-commerce. I'm planning on using Google Checkout for order processing, but aside from that and the memory constraints I don't have any real hard rules for what the framework needs to support. I'm currently running nginx to serve static content on the server, so I could potentially integrate with that, or I could just have whichever framework I end up using serve the static content as well.

So, my requirements are as follows: 1) Small memory footprint 2) Relatively simple to extend such that I can integrate it with Google Checkout 3) Documented well enough that I can figure out how to plumb everything together without needing to dig through the guts of the framework 4) Relatively stable such that a year from now I don't need to re-write the entire site because the framework isn't maintained an no longer works on the current version of GHC.

Any suggestions?

P.S. I'm interested in the quasi-quote package I saw mentioned here recently, but it looks more suited for use by framework developers rather than as a finished component, at least from the limited info I've found.

-R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat.

_______________________________________________ web-devel mailing list web-devel@haskell.org http://www.haskell.org/mailman/listinfo/web-devel

-R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat. On Thu, Apr 8, 2010 at 04:17, Alistair Bayley wrote:

Uh...

From http://hackage.haskell.org/packages/pkg-list.html#cat:web

1. happs 2. yesod 3. hack

4. salvia

5. kibro 6. hsp (barely a framework, I think)

From the descriptions of those all but kibro, and happs/yesod which have been mentioned, I would classify as bits of frameworks, rather than a full

framework like happs or yesod. Kibro looks interesting, but I can't find any documentation at all but the rather meager hadoc info on hackage itself, which tells me next to nothing about the framework. It also looks like Kibro is a CGI framework and not a full application server. Other frameworks not on hackage, possibly not under active development:

7. hvac ( http://fmapfixreturn.wordpress.com/2008/03/23/ann-hvac-01b-a-transactional-d... ) 8. turbinado ( possibly abandoned: http://github.com/alsonkemp/turbinado ) 9. WASH ( http://www.haskell.org/haskellwiki/WaSh , http://www.informatik.uni-freiburg.de/~thiemann/WASH/http://www.informatik.uni-freiburg.de/%7Ethiemann/WASH/)

Hadn't heard of Turbinado and I'm checking that out now (it at least has some documentation even if a few of the links seem to be broken). WASH likewise looks interesting, although I'm not terribly thrilled about using CGI (I will if I have to, but I'd be more comfortable with a full application server). hvac looks like it has potential, although the lack of documentation probably means I won't be using it.

There are some other bits which don't qualify as full frameworks, but might well be useful in their own right:

- HStringTemplate - formlets

And there's bound to be stuff that I've missed.

Alistair

Yes, and I've actually looked at both HStringTemplate and formlets (briefly) with the idea to either use them in conjunction with one of the other frameworks (Yesod I know uses HStringTemplate, at least for the moment, and I think Happs has some integration with formlets). As was mentioned by Gour in another followup to this, there's also Hakyll, which is an interesting possibility, but I'm not sure I'd be happy with the result. In particular it would ruin my plans for integrating with Google Checkout as I was planning on using the server side XML interface. Based on the feedback I've gotten so far, my list of possibilities in order of preferance seems to be: 1) Yesod 2) Turbinado (might change, need to look at this more) 3) Happs 4) WASH 5) Hakyll (if I can stomache using static generation) 6) All the poorly documented ones like hvac, and kibro 7) Roll my own out of the various pieces

I guess my biggest problem with the state of web development in Haskell as it currently stands is that there's no good easily accessible tutorials on how to go about doing things. There are lots of example programs scattered around, and some of them are even documented reasonably well that you can look at them and sort of figure out how they go together using the various pieces, but once you try to go beyond those specific bits and pieces you end up wandering off into the weeds. What I'm looking for most of all is one set of documentation I can look through and figure out how to put a simple application together that supports handling GET/POST requests, storing and retrieving session info, and ideally a simple long term storage solution such as HSQL. Right now I feel like just to put together a simple page that handles form submission I need to have mastered 4 or 5 different libraries, all documented in different locations. When I first started trying to do web development in Haskell I looked at the Happstack tutorials, and that worked fairly well, I was able to take a simple paste bin application and modify it to add some javascript into the generated page, however even that fairly trivial modification meant I had to go digging through the Text.XHTML documentation, which consisted solely of the automaticlly generated hadock. Furthmore I'm still not entirely sure how the various pieces of Happs actually fit together, or what pieces are provided by Happs, and what pieces are provided by other external libraries. Yesod is a similar situation in which I'm not entirely sure what's provided where and where to go to find the documentation of that. I'm sure an expert Haskell developer can just glance over the hadock for a library and figure out how to put all the pieces together, but as a Haskell newbie I often get lost trying to figure out how to do things that in other languages would be fairly trivial. Most of the time when I'm lost on how to do something it isn't even because what I want to do is terribly difficult, it's just that the documentation on how to do something assumes that you essentially already know how to do it and are just looking for clarrification on the details, a situation that I usually resolve by either trial and error, or by looking for some piece of code somewhere that does what I want and trying to puzzle out how it actually goes about doing that. Part of this seems to be caused by most of the libraries/frameworks being documented solely in hadock, which is ok for a quick reference, but sucks for trying to learn how to use a library/framework. Even though it's true there's a lot of usefull info contained in just the signature of a function, if that's the first time you've been exposed to that function and aren't entirely sure of its purpose, that information isn't enough to really understand the function, at least for non-trivial functions. The big frameworks like Happs, Turbinado, and hopefully soon Yesod, do seem to be fairly well documented, but the fact that they're built on top of a bunch of the other libraries like HSQL, HStringTemplate, and Text.XHTML that aren't well documented undermines the ability to fully understand them, as before you can really make the most use out of their documentation you must first go puzzle your way through the poor documentation of all the support libraries. Further complicating matters is the scattered way in which libraries are documented. For all I know, there's really excellent documentation for Text.XHTML, but just looking at it on hackage, and a quick google search doesn't seem to reveal anything particularly useful. The hackage page for Text.XHTML has a link for more info, but going to the page that supposedly contains more info I'm greeted with a 404 page. It would be one thing if this was the exceptional case, but from what I've seen that's pretty much par for the course. -R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat. On Thu, Apr 8, 2010 at 10:15, Sebastiaan Visser wrote:

Kyle,

What functionality do you need? What do you want this `framework' to offer you? There are plenty of packages for Haskell that help you to write web applications, all of them offering some functionality. It's very unlikely you'll find one single package that satisfies all your requirements.

I advice you to look around and see what package there are and how these might help you.

For example, I'm currently thinking about building a web application using: - The Salvia server interface (not surprisingly, this one is written by me) - The Haskell bindings to the Berkeley XML database for long-term storage. - The Salvia-session package for in-memory session storage. - The HXT xml library. - The regular-xmlpickler for generic XML printing/parsing (using HXT picklers). - The BlazeHtml package for building up HTML pages (fast). - The formlets package for generating flexible web forms. - The CleverCSS package (and salvia integration) for improved css support. - probably even more...

Although I agree it is not always easy to get a grip on what are the best techniques available for Haskell web development, there are plenty of tools available. It will probably take some time to get to know all these libraries, but due to the clear separation of concerns and Haskell's neat type system, integration is almost never a problem.

I sincerely hope this might help you and does not scare you :-)

Regards,

Sebastiaan

...

-R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat.

On Thu, Apr 8, 2010 at 04:17, Alistair Bayley wrote: Uh...

...

From http://hackage.haskell.org/packages/pkg-list.html#cat:web

1. happs 2. yesod 3. hack 4. salvia 5. kibro 6. hsp (barely a framework, I think)

From the descriptions of those all but kibro, and happs/yesod which have been mentioned, I would classify as bits of frameworks, rather than a full

On Apr 8, 2010, at 3:29 PM, Kyle Murphy wrote: framework like happs or yesod. Kibro looks interesting, but I can't find any documentation at all but the rather meager hadoc info on hackage itself, which tells me next to nothing about the framework. It also looks like Kibro is a CGI framework and not a full application server.

...

Other frameworks not on hackage, possibly not under active development:

7. hvac (

...

) 8. turbinado ( possibly abandoned: http://github.com/alsonkemp/turbinado) 9. WASH ( http://www.haskell.org/haskellwiki/WaSh , http://www.informatik.uni-freiburg.de/~thiemann/WASH/http://www.informatik.uni-freiburg.de/%7Ethiemann/WASH/)

Hadn't heard of Turbinado and I'm checking that out now (it at least has some documentation even if a few of the links seem to be broken). WASH

http://fmapfixreturn.wordpress.com/2008/03/23/ann-hvac-01b-a-transactional-d... likewise looks interesting, although I'm not terribly thrilled about using CGI (I will if I have to, but I'd be more comfortable with a full application server). hvac looks like it has potential, although the lack of documentation probably means I won't be using it.

...

There are some other bits which don't qualify as full frameworks, but might well be useful in their own right:

- HStringTemplate - formlets

And there's bound to be stuff that I've missed.

Alistair

Yes, and I've actually looked at both HStringTemplate and formlets

(briefly) with the idea to either use them in conjunction with one of the other frameworks (Yesod I know uses HStringTemplate, at least for the moment, and I think Happs has some integration with formlets).

...

As was mentioned by Gour in another followup to this, there's also

Hakyll, which is an interesting possibility, but I'm not sure I'd be happy with the result. In particular it would ruin my plans for integrating with Google Checkout as I was planning on using the server side XML interface.

...

Based on the feedback I've gotten so far, my list of possibilities in

order of preferance seems to be:

...

1) Yesod 2) Turbinado (might change, need to look at this more) 3) Happs 4) WASH 5) Hakyll (if I can stomache using static generation) 6) All the poorly documented ones like hvac, and kibro 7) Roll my own out of the various pieces

You're 100% correct about the state of documentation. I think we need to figure out a nice, centralized place to put up quality Haskell documentation, and actually work at it.

My feeling is that we lack mostly short, tutorial-style introductions, that just get you started with a topic/library. Ideally we'd have a way to automatically verify (say test) that those examples actually work. Haddock 'head' has some very new and immature support for 'examples', and I'm working on integrating it with my DocTest package. Besides that, a way to write larger tutorials (that we can test) would also be nice.

I'm more than open to better suggestions. I'll also appreciate any help in improving my documentation.

I'm working on a (very) short introduction to WAI, not sure when I'll have time to finish it. Cheers, Simon

On Fri, Apr 9, 2010 at 3:32 AM, Gour 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

On Fri, Apr 9, 2010 at 13:04, Gour wrote:

OK. Let's wait that Yesod becomes more mature, then we'll evaluate it again.

Fair enough.

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.

The problem is really that there's multiple levels of documentation. At the lowest, and least "user friendly" you've got the haddock which isn't much more than a collection of function signatures. It assumes that if you're reading it, you're already more or less familiar with the framework and how to go about doing what you want. The next highest level of documentation, what's severely lacking in the Haskell community in general, and the web development community in particular, is the in depth documentation for the libraries/frameworks. These documents aren't quite tutorials, but they go beyond just telling you the minimal information you need to use a function. This sort of document would typically have a section for each of the major use cases of your framework/library, and possibly a few brief code snippets showing how you go about doing particular things. For instance, in the Text.XHTML package, this document would most likely list the various functions for generating html elements like br, as well as have a section talking about the attribute op (!), the Html concatination op (+++), and the Html nesting op (<<), and provide examples of how to construct a few example pages. It's this level of documentation that's really missing, and where most people would head to once they finish following along on some tutorial. If all the libraries you used in your tutorials provided this level of documentation all you would need to do in your tutorial is to mention which libraries you used, and if you're feeling generous provide a link to their documentation. Unfortunately, that's not the state that the vast majority of Haskell libraries are in, there being only haddock, and if you're lucky a tutorial or two. This unfortunately puts the tutorial writers in a rather awkward position where even if the main framework, happs lets say, is well documented, all the support libraries that are necessary to put together a working tutorial aren't, and thus confuse newbies looking to use the tutorial. One solution, although a rather bad one, is for the tutorial writers to help fill in the missing documentation, either directly, or by writing yet more tutorials to document the support libraries. This is bad for a number of reasons, not the least of which is that a tutorial isn't the place to document huge swaths of a framework, which is something best left to the intermediate documentation mentioned previously (with the haddock being used to document the minute details, and the not often visited cranies). The other reason this is a bad solution is that as an example, the creator of Yesod, who decides to write a tutorial on using it, should not then be obliged to create documentation for lets say HStringTemplate just because he happens to need it for his tutorial. The better long term solution is to encourage some kind of detailed documentation to be produced for the majority of Haskell libraries. I'm hesitant to say it should be required, as obviously such a requirement might discourage people from bothering to share the work they do, but at the same time something needs to be done to encourage documentation beyond the simple haddock that's used as the sole documentation of the vast majority of libraries (many of which don't even provide anything in the haddock besides the function signature, something that's easy enough to get from ghci). As a final thought, haddock itself might even be leveraged to provide this higher level documentation, it certainly has the capability of doing so, it just generally isn't used in that way. The brief summary most people put at the top of the generated haddock, which usually consists of a one or two sentence description of what the library provides, could instead be used to provide details of all the use cases, and links to the appropiate pieces of documentation. As an example, consider this documentation of the Java Pattern class ( http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html ). If the majority of Haskell libraries contained as thorough documentation as that in their haddock, you'd rarely even need to consult a tutorial or other documentation. -R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat.

On Fri, 9 Apr 2010 14:07:28 -0400

...

...

...

...

...

"Kyle" == Kyle Murphy wrote:

Kyle> The next highest level of documentation, what's severely lacking Kyle> in the Haskell community in general, and the web development Kyle> community in particular, is the in depth documentation for the Kyle> libraries/frameworks. These documents aren't quite tutorials, Kyle> but they go beyond just telling you the minimal information you Kyle> need to use a function. This sort of document would typically Kyle> have a section for each of the major use cases of your Kyle> framework/library, and possibly a few brief code snippets Kyle> showing how you go about doing particular things. For instance, Kyle> in the Text.XHTML package, this document would most likely list Kyle> the various functions for generating html elements like br, as Kyle> well as have a section talking about the attribute op (!), the Kyle> Html concatination op (+++), and the Html nesting op (<<), and Kyle> provide examples of how to construct a few example pages. It's Kyle> this level of documentation that's really missing, and where Kyle> most people would head to once they finish following along on Kyle> some tutorial. If we consider that Django is nicely documented and can be used as example, do you think about stuff called 'topic guides' listed at http://docs.djangoproject.com/en/dev/intro/whatsnext/#intro-whatsnext i.e. something in between tutorial and API reference? Here is blog post about it: http://jacobian.org/writing/great-documentation/what-to-write/ Kyle> As a final thought, haddock itself might even be leveraged to Kyle> provide this higher level documentation, it certainly has the Kyle> capability of doing so, it just generally isn't used in that way. Kyle> The brief summary most people put at the top of the generated Kyle> haddock, which usually consists of a one or two sentence Kyle> description of what the library provides, could instead be used Kyle> to provide details of all the use cases, and links to the Kyle> appropiate pieces of documentation. Long ago I was suggesting on 'cafe' that it would be nice if the haddock documentation would have some 'examples of usage', but it looks it is too much and we are still far from it... Sincerely, Gour -- Gour | Hlapicina, Croatia | GPG key: F96FF5F6 ----------------------------------------------------------------

I managed to find some time to put together an example update of the documentation for xhtml package with the sorts of changes I'd like to see applied to as much of hackage as possible.you can find the udated haddock at http://tenletters.org/haddock/index.html Depending on the feedback I get on this updated documentation I might try to get in touch with the xhtml maintainer and have my changes merged in to the official repository. Let me know what you guys think. -R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat. On Fri, Apr 9, 2010 at 15:02, Kyle Murphy wrote:

That blog post was excellent and fairly well captures the spirit of what I was getting at, although I do disagree somewhat about the auto-generated docs. I don't have any problem with auto-generated docs in and of themselves, assuming that you also insert into that documentation the sort of details discussed in the "topic guides". A great example of this is most of the POD used in Perl modules, where at least the first few paragraphs of documentation are typically devoted to essentially being a "topic guide" for that module. I think what she was really complaining about in that post is exactly the situation we have in hackage currently where there is for all intents and purpose absolutely no documentation provided for the vast majority of libraries beyond the automatically generated signatures and the odd sentence or two.

Something I'd like to see become common in haddock is for instance, a good general description, with references to sub-modules in the main module of a package. Each sub-module would then function as a topic guide for the features of that module, with the specific API details contained in the function descriptions. If I have some time this weekend maybe I'll pull down the source for Text.XHTML, and try to update its documentation to provide an example of what I'm getting at.

-R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat.

On Fri, Apr 9, 2010 at 14:36, Gour wrote:

...

On Fri, 9 Apr 2010 14:07:28 -0400

...

...

...

...

>> "Kyle" == Kyle Murphy wrote:

Kyle> The next highest level of documentation, what's severely lacking Kyle> in the Haskell community in general, and the web development Kyle> community in particular, is the in depth documentation for the Kyle> libraries/frameworks. These documents aren't quite tutorials, Kyle> but they go beyond just telling you the minimal information you Kyle> need to use a function. This sort of document would typically Kyle> have a section for each of the major use cases of your Kyle> framework/library, and possibly a few brief code snippets Kyle> showing how you go about doing particular things. For instance, Kyle> in the Text.XHTML package, this document would most likely list Kyle> the various functions for generating html elements like br, as Kyle> well as have a section talking about the attribute op (!), the Kyle> Html concatination op (+++), and the Html nesting op (<<), and Kyle> provide examples of how to construct a few example pages. It's Kyle> this level of documentation that's really missing, and where Kyle> most people would head to once they finish following along on Kyle> some tutorial.

If we consider that Django is nicely documented and can be used as example, do you think about stuff called 'topic guides' listed at

http://docs.djangoproject.com/en/dev/intro/whatsnext/#intro-whatsnext

i.e. something in between tutorial and API reference?

Here is blog post about it:

http://jacobian.org/writing/great-documentation/what-to-write/

Kyle> As a final thought, haddock itself might even be leveraged to Kyle> provide this higher level documentation, it certainly has the Kyle> capability of doing so, it just generally isn't used in that way. Kyle> The brief summary most people put at the top of the generated Kyle> haddock, which usually consists of a one or two sentence Kyle> description of what the library provides, could instead be used Kyle> to provide details of all the use cases, and links to the Kyle> appropiate pieces of documentation.

Long ago I was suggesting on 'cafe' that it would be nice if the haddock documentation would have some 'examples of usage', but it looks it is too much and we are still far from it...

Sincerely, Gour

--

Gour | Hlapicina, Croatia | GPG key: F96FF5F6 ----------------------------------------------------------------

_______________________________________________ web-devel mailing list web-devel@haskell.org http://www.haskell.org/mailman/listinfo/web-devel

On Fri, Apr 9, 2010 at 8:06 AM, Michael Snoyman wrote:

On Fri, Apr 9, 2010 at 3:32 AM, Gour 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

6. hsp  (barely a framework, I think)

HSP is a templating system, indeed not a full framework*. You'd use it together with happstack ftw (and possibly any other server framework, should be modular enough). :-) /Niklas * At one point it used to be, back when there were no other real server frameworks available, but we cut support for all that stuff when happs came along and did things better.