<br><div class="gmail_quote">On Fri, Apr 9, 2010 at 13:04, Gour <span dir="ltr">&lt;<a href="mailto:gour@gour-nitai.com">gour@gour-nitai.com</a>&gt;</span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">

OK. Let&#39;s wait that Yesod becomes more mature, then we&#39;ll evaluate it<br>
again.<br></blockquote><div><br>Fair enough. <br></div><div> </div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">Well, I agree it&#39;s not easy to put ineself in another&#39;s shoes, but<br>

here lies the difference. ;)<br></blockquote><blockquote style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;" class="gmail_quote"><div> <br></div></blockquote><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">

Michael&gt; As far as we&#39;re concerned, our code is beautiful, elegant,<br>
Michael&gt; simple and self-documenting (until we look at it again six<br>
Michael&gt; months later).<br>
<br>
:-)<br>
<br>
Michael&gt; We really need an outside voice to tell us what&#39;s lacking.<br>
<br>
Simple tutorials to get us going. Have you seen the Django tutorial<br>
written in several parts?<br>
<br>
Michael&gt; So instead of saying &quot;fizzbuzz has no documentation,&quot; maybe<br>
Michael&gt; say &quot;I saw the fizzbuzz tutorial on creating foobars, but I<br>
Michael&gt; couldn&#39;t figure out how to extend that for wibbles. Could you<br>
Michael&gt; write a tutorial for that?&quot;<br>
<br>
Well, at the moment I am playing with Hakyll and can just recommend<br>
every library writer to check Hakyll&#39;s tutorials at<br>
<br>
<a href="http://jaspervdj.be/hakyll/tutorials.html" target="_blank">http://jaspervdj.be/hakyll/tutorials.html</a><br>
<br>
Psychologically it is very encouraging to be provided with few simple<br>
steps and achieve something instead of starring at the<br>
Haddock-generated docs only.<br>
<br>
Even the Haskell language (which is not at all simple) has &quot;Haskell<br>
in 5 steps&quot; &amp; &quot;Learn Haskell in 10 minutes&quot; tutorials.<br>
<br>
One may say it&#39;s kind of cheating, but if the easy introductory<br>
material sparks enough interest in the noob user, there is good chance<br>
that he/she will investigate further.<br></blockquote><div><br>The problem is really that there&#39;s multiple levels of
documentation. At the lowest, and least &quot;user friendly&quot; you&#39;ve got the
haddock which isn&#39;t much more than a collection of function signatures.
It assumes that if you&#39;re reading it, you&#39;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&#39;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&#39;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 (&lt;&lt;), and provide examples of how
to construct a few example pages. It&#39;s this level of documentation
that&#39;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&#39;re feeling generous provide a link to their documentation.
Unfortunately, that&#39;s not the state that the vast majority of Haskell libraries are in, there being only haddock, and if you&#39;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&#39;t, and thus confuse newbies looking to use the tutorial.<br>
<br>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&#39;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.<br>
<br>The better long term solution is to encourage some kind of detailed documentation to be produced for the majority of Haskell libraries. I&#39;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&#39;s used as the sole documentation of the vast majority of libraries (many of which don&#39;t even provide anything in the haddock besides the function signature, something that&#39;s easy enough to get from ghci).<br>
<br>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&#39;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 ( <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html">http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html</a> ). If the majority of Haskell libraries contained as thorough documentation as that in their haddock, you&#39;d rarely even need to consult a tutorial or other documentation.<br>
</div></div><br clear="all">-R. Kyle Murphy<br>--<br>Curiosity was framed, Ignorance killed the cat.<br>
<br>