On a somewhat related note, I think the Haskell documentation in general is rather <br>patchy and hard to follow for most things. Part of that I think is because of the <br>confusion between the different forms of documentation. In general as a programmer<br>
I expect to find three kinds of documentation available, preferably in a centralized<br>location, but at least in a handful of standardized locations. The first kind, is what<br>Haskell has in abundance, and what is hosted in Hackage, which is API documentation.<br>
API documentation is written to be terse, to assume you already know how library<br>Foo works (and probably library Bar and Baz too), and you just need to refresh<br>yourself on exactly what the signature of function wibble was exactly. Really good<br>
API documentation also fills the role of some of the other kinds of documentation<br>and has some quick examples sprinkled around the most commonly used functions<br>and maybe a nice intro paragraph with even more examples and some suggestions<br>
for further information. The second kind of documentation which is very nearly<br>non-existant for most Haskell packages is a user manual that documents in detail<br>all the functions and data types of a package, how you use them, and the ideas<br>
and concepts they&#39;re based on. Given only this documentation, a firm understanding<br>of the language, and a basic knowledge of the problem domain, anyone should be<br>able to write an application using your library. If they have to spend three hours<br>
trying to track down some obscure research paper that&#39;s referenced in your<br>documentation a half dozen times in as many functions, you&#39;re not providing<br>enough detail and assuming too great a knowledge of the domain. The last kind<br>
of documentation which is fortunately somewhat more prevalent then the previous<br>kind is the classic tutorial, which documents and thoroughly explains the most <br>commonly used functions in your library (not to be confused with thoroughly explaining <br>
your library which is the job of the user manual). There are quite a few good tutorials <br>on Haskell in general, Monads specifically, and a lot of random bits and pieces floating <br>around on the net, and thankfully collected for reference on the Haskell wiki.<br>
<br>On the whole, the Haskell API docs are decent (although most of them are not what I<br>would call &quot;Good&quot;), and the tutorials are also rather plentiful, but the user manuals<br>are practically non-existent. What would be ideal is if the hackage entry for each<br>
package also included a link to the user manual for that package if it exists (and<br>hopefully most of them would exist) in addition to the links to the API docs and<br>homepage it already has (I suppose in theory the homepage link can serve this<br>
purpose and in some cases it currently does, but an actual &quot;manual&quot; link would be<br>nice).<br><br>(All of the following were chosen at random)<br><br>For reference, here is a good example of an API doc:<br><a href="http://hackage.haskell.org/package/zlib">http://hackage.haskell.org/package/zlib</a><br>
<br>Average API docs (but with links to good user manual and tutorial):<br><a href="http://hackage.haskell.org/package/DeepArrow">http://hackage.haskell.org/package/DeepArrow</a><br><br>Bad API docs (but once again with a link to average manual/tutorial):<br>
<a href="http://hackage.haskell.org/package/actor">http://hackage.haskell.org/package/actor</a><br><br>-R. Kyle Murphy<br>--<br>Curiosity was framed, Ignorance killed the cat.<br>
<br><br><div class="gmail_quote">On Mon, Oct 12, 2009 at 16:29, John Lato <span dir="ltr">&lt;<a href="mailto:jwlato@gmail.com">jwlato@gmail.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;">
&gt; From: Derek Elkins &lt;<a href="mailto:derek.a.elkins@gmail.com">derek.a.elkins@gmail.com</a>&gt;<br>
<div class="im">&gt;<br>
&gt; On Sun, Oct 11, 2009 at 8:55 AM, Iain Barnett &lt;<a href="mailto:iainspeed@gmail.com">iainspeed@gmail.com</a>&gt; wrote:<br>
&gt;&gt;<br>
&gt;&gt; On 11 Oct 2009, at 13:58, John Lato wrote:<br>
&gt;&gt;<br>
&gt;&gt;&gt; For anyone writing introductions to generic programming, take this as<br>
&gt;&gt;&gt; a plea from Haskellers everywhere.  If one of the RWH authors can&#39;t<br>
&gt;&gt;&gt; understand how to make use of these techniques, what hope do the rest<br>
&gt;&gt;&gt; of us have?<br>
&gt;&gt;&gt;<br>
&gt;&gt;&gt; John Lato<br>
&gt;&gt;&gt;<br>
&gt;&gt;&gt; P.S. Some might wryly note that I&#39;m the maintainer of a package which<br>
&gt;&gt;&gt; is also known for incomprehensible documentation.  To which I would<br>
&gt;&gt;&gt; reply that our effort is much newer, I consider it a problem, and it&#39;s<br>
&gt;&gt;&gt; being worked on, contrasted to the state of GP where similarly<br>
&gt;&gt;&gt; impenetrable documentation has been and continues to be the norm.<br>
&gt;&gt;&gt;<br>
&gt;&gt;<br>
&gt;&gt; You could say that about most documentation (for Haskell and beyond).<br>
&gt;&gt; Apparently, programmers like programming better than documenting. The effect<br>
&gt;&gt; of this is that less people use their programming, making their efforts<br>
&gt;&gt; redundant.<br>
&gt;&gt;<br>
&gt;&gt; Silly really, considering programmers are (allegedly:) intelligent.<br>
&gt;<br>
&gt; Apparently, programmers like programming better than reading as<br>
&gt; well... in my experience.<br>
<br>
</div>I won&#39;t disagree.  But I think the real difficulty is that the<br>
intersection of programmers who can come up with really good ways to<br>
solve problems (not even all programmers, unfortunately) and people<br>
who are good at writing documentation is vanishingly small.<br>
<br>
It seems to me that when someone works in a problem domain (e.g.<br>
Generic Programming), they gain a very deep understanding of that area<br>
and are used to working at a certain level within it.  When<br>
introducing the topic to newcomers (even ostensibly smart programmers)<br>
the introduction can&#39;t assume prior knowledge of the problem domain,<br>
but the authors are so used to thinking at one level they often take<br>
for granted knowledge that the audience doesn&#39;t have.<br>
<br>
I don&#39;t think this problem is particular to programming, but it is<br>
common in Haskell.  Most likely because Haskell, with a reputation as<br>
a research language, has a lot of computer science types doing<br>
research in wide-ranging topics.  Somebody&#39;s expertise in category<br>
theory, for example, might not directly carry over to generic<br>
programming (or maybe it does; I&#39;m not an expert in either).<br>
<div><div></div><div class="h5">_______________________________________________<br>
Haskell-Cafe mailing list<br>
<a href="mailto:Haskell-Cafe@haskell.org">Haskell-Cafe@haskell.org</a><br>
<a href="http://www.haskell.org/mailman/listinfo/haskell-cafe" target="_blank">http://www.haskell.org/mailman/listinfo/haskell-cafe</a><br>
</div></div></blockquote></div><br>