<div> Andrew Coppin <span dir="ltr"><<a href="mailto:andrewcoppin@btinternet.com">andrewcoppin@btinternet.com</a>></span> wrote: <br></div><blockquote style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;" class="gmail_quote">
how do we fix all this?<br></blockquote><br>I think the key here is to reduce the cost of contribution to a minimum. Make it as easy as possible to contribute an example, or to fill in some missing documentation (and to find it later).<br>
<br>Cabal and hackage have made it very easy to contribute and fetch packages and I think this is the primary reason why there are so many hackage packages. We need to make it even easier to contribute documentation.<br><br>
I think having some haddock/wiki system that allowed user contributions which could be displayed alongside the official package dos and an easy way for package maintainers to incorporate the user supplied documentation into the official package documentation would be very helpful.<br>
<br>To sum up:<br>1. Make it stupidly easy to contribute documentation, notes, comments, examples<br>2. Make sure all of this good stuff can be easily accessed in one place.<br><br>- Job<br><br><div class="gmail_quote">
On Tue, Sep 29, 2009 at 3:36 PM, Andrew Coppin <span dir="ltr"><<a href="mailto:andrewcoppin@btinternet.com">andrewcoppin@btinternet.com</a>></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;">
<div class="im">Tom Tobin wrote:<br>
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
This. As an experienced Pythonista but a beginning Haskeller, there<br>
is *no way* I would have been able to wrap my head around the basics<br>
of Haskell without the tutorage of Learn You A Haskell, Real World<br>
Haskell, and various smaller tutorials scattered around the Haskell<br>
wiki — but I still find the array of libraries confusing (just what<br>
comes with GHC — I'm not even talking about Hackage here), since the<br>
documentation seems to be quite terse compared to Python's docs. I'm<br>
getting better at reading the code directly, but I'm often at a loss<br>
for what a particular library is good for in the first place. The<br>
library documentation seems to assume a mathematical or (advanced)<br>
computer science background, and has no problem sending a reader off<br>
to see a journal paper for details — not exactly friendly to those who<br>
are trying their hardest to unlearn their imperative ways as it is.<br>
;-<br>
</blockquote>
<br></div>
While some of the stuff that comes with GHC is quite well documented, others are highly under-documented. (As an exercise, go count how many module descriptions say "inspired by the paper by XXX at this URL"...)<br>
<br>
Admittedly, the System.IO module probably isn't the place to explain what a monad is and write a full tutorial on using them. However, look at (say) Control.Concurrent.STM.TVar. In my copy (GHC 6.10.3) it lacks even type signatures, let alone actual descriptions. Similarly, Parsec has some lovely external documentation (unfortunately as a single giant HTML page), but the Haddock stuff is bare.<br>
<br>
Now, the operative question (and I'm sure we've debated this one before) is: how do we fix all this?<div><div></div><div class="h5"><br>
<br>
_______________________________________________<br>
Haskell-Cafe mailing list<br>
<a href="mailto:Haskell-Cafe@haskell.org" target="_blank">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>